Poseidon for UML: User Guide
Prev | Chapter 14. Generation | Next

# 14.3. Documentation Generation

Generating corresponding HTML and Word 2003 documentation for your model is available in every edition except the Community Edition. The generated documentation is similar to Javadocin that it includes specific Javadoc information entered directly in your model (in the Documentation tab). This information, such as comments to your classes or methods, is included in the code. But Javadoc provides a view of the code only, not of the model - you do not see your diagrams. With the HTML doc feature you get the same information as with Javadoc, in addition to class, use case, activity, and state machine diagrams from your model. The remaining diagram types may be included in the documentation, but they are not yet supported or configurable.

Note that from within Poseidon, the default browser is Netscape. This is not configurable in this version; however, workarounds are available. For instance, in Linux you can create a soft link from Netscape to Mozilla with the command: ln -s /usr/local/share/mozilla netscape . Now Poseidon should open external links on your system with Mozilla

## 14.3.1. HTML Preview

The HTML Preview button opens the 'Book Management' dialog. To open an HTML preview, select the desired book(s) and click the 'Open Selected' button.

A tab for each book is added to the Diagram pane, as when new diagrams are created. The left side displays the tree view of the documentation, the right side is the actual HTML preview.

In the tree view, items can be rearranged, added, and deleted as necessary. Please review Section 14.3.2.2 for more specific information about the behavior of the tree.

When the book has been completed to your satisfaction, you can generate HTML with the Generate HTML button, or generate Word with the Generate Word button.

Book Management Buttons

| Open Selected
| Add New
| Delete Selected
| Duplicate Book

Filter Set Management

Also available from Book Management is the Filter Set Management dialog. This dialog allows you to create, edit, and delete the filter sets which determine the elements included in the documentation.

## 14.3.2. Generation Dialog (for Poseidon 5.x and lower)

The HTML Generation dialog is accessible from the toolbar button or the Generation menu of every edition except the Community Edition, and can generate both HTML and Microsoft Word 2003 documentation from one dialog. To generate HTML, click the 'Generate...' button. For Word, click 'Word Generate...'

Select a Word Style Template

When generating word documents, a generation dialog prompts for the selection of a style template.

- Default - applies the styles included in umldoc.jar

- Re-use from generation target - applies the same styles as the current version of the document. This option is only available if the target document already exists.

- Style template - applies a specified XML file to the resulting documentation. Use the ellipsis button to browse to the location of the XML file or type the path directly.

### 14.3.2.1. Project Tree

The project tree is a list of all available elements that can be dragged to the chapter tree. This tree cannot be reordered, nor can elements be deleted.

The top node of the tree is the project itself. The first element below that is the Table of Contents, followed by a package-centric view of the supported elements, then a diagram-centric view of the supported diagrams. Finally, the list of indices is presented.

### 14.3.2.2. Chapter Tree

The chapter tree displays all elements and diagrams that will be included in the documentation, in the order that they will appear.

Changing the Chapter Tree Nesting

Packages may be displayed with either deep or flat nesting. The project tree uses the standard deep nesting, where the packages are displayed indented and below their parent packages. The chapter tree allows for flat nesting that reduces the the number of hierarchy levels. Flat nesting can be assigned per package via the nesting toggle buttons that appear when hovering over the name of a package.

Reordering Elements

Elements can be reordered by dragging them to the appropriate location. A bar indicates where the element will be dropped, and a slashed circle indicates that the selected element cannot be dropped into that location.

Adding Elements

New elements are added by dragging them from the project tree; the elements are not removed from the project tree, meaning they may be reused and inserted in multiple locations in the document.

Removing Elements

Elements that appear automatically from the template are excluded from the documentation by disabling their checkboxes. Elements that have been dragged from the content tree and the top level nodes ('table of contents', 'diagram tree', 'models', and 'indices') can either be deleted from the chapter tree by pressing 'delete' on the keyboard, or disabled with their checkbox.

Renaming Elements

Any element, book, or book template can be renamed by double-clicking on the name to open the inline editor. The name of a book or book template will simply change. The name of an element will display the new name, followed in parenthesis by the original name of the element in the model. For example, in the model, a class has the name 'Class_1'. After it is renamed, it will show 'NewClassName (Class_1)'.

### 14.3.2.3. Books

A single cohesive model can be used to communicate different aspects of the project to a variety of audiences. The diagrams include or exclude information as necessary to perform their intended function.

As of Poseidon 3.1, the same principle is applied to HTML documentation. One model can define separate books, each containing only the information necessary for the intended audience. Perhaps an analyst must communicate with non-technical colleagues in order to compile a collection of business practices. The non-technical people may not be interested in class diagrams, but would find certain use case diagrams or state machine diagrams ideal. These particular diagrams can be added to a book for just this audience. The same model can also contain a separate book aimed at programmers, which might contain all of the class diagrams.

A book is an organizational unit that not only defines the structure of the chapter hierarchy, but also the style settings for each document. The book list displays the names of all of the defined books for the current project. Click on a book name to display the book in the right-hand pane. Each book is stored within the Poseidon project file.

Renaming Books

A book can be renamed simply by double-clicking the book name to open the inline editor in either the chapter tree or the book list, then typing in the new name.

Creating a New Book

To create a new book, select a template from the book template list, then click the 'Create Book' button.

### 14.3.2.4. Book Templates

A book template is independent of any project and contains the chapter hierarchy on a type level. It refers to no specific model element, but instead to types of model elements, such as classes or states. Although specific elements of the book upon which the template is based will be displayed, these elements will have no effect on the template or any book subsequently using this template.

To illustrate, a book has a class 'Foo' and the documentation of this class is disabled. This book is used to create a book template. A new book in a different project is created based on the template, and this book also has the class 'Foo'. The template will not affect the second book.

Book templates are not stored in individual project files, so they are available to all projects.

Renaming Book Templates

A book template can be renamed simply by double-clicking the book template name to open the inline editor in the book template list, then typing in the new name.

Creating a New Book Template

To create a new book template, select a book from the book template list, then click the 'Create Template' button.

Editing a Book Template

Book templates take the structure and settings of the current book. To edit a book template, select the book template, create a new book from that template, edit the book, then use the edited book to create a template.

### 14.3.2.5. Settings Tab

The Settings tab indicates which elements are to be included on a book level. Individual settings are not possible at this time, e.g. if the checkbox for class attributes is disabled, no class attributes will be included throughout the entire book.

## 14.3.3. Included Diagrams

Class, Use Case, State Machine, Sequence, and Activity diagrams are fully supported by the documentation plug-in. They are included in the diagram trees of the generation dialog, listed in the indices, and all of their element types may be documented.

Unsupported diagram graphics may still appear in the documentation, but the configuration options are limited. They are not listed in the indices or diagram trees, and the element types from these diagrams which may have documentation are element types which may appear in the supported diagrams.

For example, a deployment diagram graphic may appear in the documentation, but the name of the diagram will not be listed and the summary section for the diagram will be empty. Associations in this diagram may appear in the indices and have their own documentation because they are allowed in the supported diagrams. Nodes, on the other hand, are not allowed in any of the supported diagrams, therefore they are not included in the documentation.

## 14.3.4. Supported Javadoc Tags

Currently UMLdoc generates output for the following Javadoc tags, all unknown tags are skipped and do not produce output.

@author [author name]

  Adds the specified author name to the model element documentation, output is only produced if you have selected the Generate authors doc option in the UMLdoc code generation settings.

@deprecated [text]

  Adds a comment indicating that this API should no longer be used (even though it may continue to work).

@exception, @throws [exception type] [description]

  Adds an exception description to the method documentation.

@gentleware-originalType

  Notes the original type of an attribute with an unlimited upper bound which has been typed as a Collection.

{@link package.class#member label }

  Inserts an in-line link with visible text that points to the documentation for the specified package, class, or member name of a referenced class.

  Also generates external links. Any types from Java will be automatically linked to Sun's Java site, and other links can be created utilizing the @link tag. Additionally, any URL included in the documentation will be automatically detected and the link will be activated without requiring any other notation.

@param [param name] [description]

  Adds a parameter description to the method documentation.

@return [description]

  Adds a return parameter description to the method documentation.

@see [reference]

  Adds a "See Also" heading with a link or text entry that points to a reference.

@serial [description]

  Adds a comment indicating a default serializable field. The optional description should explain the meaning of the field and list the acceptable values.

@serialData [description]

  Documents the sequences and types of data written by the writeObject method and all data written by the Externalizable.writeExternal method.

@serialField [name] [type] [description]

  Documents an ObjectStreamField component of a Serializable class' serialPersistentFields member.

@since [release name]

  Adds a description indicating that this change or feature has existed since the software release specified.

@version [version]

  Adds a version to the method documentation. A doc comment may contain at most one @version tag.

Prev | Home | Next
Advanced Code Generation | Up | Plug-Ins