Documentation Generation

For generating the corresponding HTML documentation for your model you need the UMLdoc feature, which is available in every edition except the Community Edition. Users of any edition, including the Community Edition, can utilitze the UMLdoc Online Service. The look and feel of the generated documentation is very similar to Javadoc. Poseidon for UML allows you to specify Javadoc information directly in your model (in the Documentation tab). This information, such as comments to your classes or methods, is included in the code. But unlike UMLdoc, Javadoc provides a view of the code only, not of the model. For example, you do not see your diagrams. With the UMLdoc feature you get the same information as with Javadoc, in addition to all diagrams from your model. This includes Class diagrams, Use Case diagrams, sequence diagrams etc. This is valuable information that you would want in your documentation.

UMLdoc

The UMLdoc Plug-In generates HTML documentation files, that look similar to Javadoc. But it includes your UML diagrams as jpeg images, and offers an improved navigation. Currently UMLdoc generates documentation for models, packages, classes, interfaces, operations, methods, associations, actors, use cases, extend and include relationships.

UMLdoc is also capable of generating 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.

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.

After the generation is finished, you will get a corresponding message in the Generator/Compiler output. Now you can open the HTML documentation in your favorite browser. UMLdoc generates an HTML page for the model overview, each package and each classifier (actors, use cases, classes, interfaces). They are connected by hyperlinks, so that you can easily navigate through the whole document.

Figure 14-6. Generated UMLdoc opened in Netscape.

Figure 14-7. Code Generation dialog and settings - UMLdoc

Generation Settings

The code generation settings dialog of UMLdoc provides the following settings:

Generate author docs

If you disable this setting, @author tags are skipped in the output.

Generate class doc for

Here you can select for which classes documentation should be generated. You can enable/disable the documentation output of public, protected and private classes.

External Link Base

The site noted here will be used as the base link for all external links within the document. The default points to Sun's Java site, and this site can be restored after modifications by clicking 'Set Default'.

Generate External Links

With this option enabled, @link destinations that are external will be activated within the document.

Figure 14-8. UMLdoc code generation - settings.

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.

{@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.

@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.