This guide shows how to add documentation comments (short: adoc-comments) to plantuml-files. These adoc-comments are used by the UML2adoc script to generate documentation fragments.

1. General rules for adoc-comments

  • Only use multi-line comments /'adoc …​ '/` for adoc-comments that shall appear in the adoc fragment!
    (Single-line comments ’…​     can still be used for commenting out parts of the plantuml or for comments that shall not appear in the adoc fragment)

  • Put adoc-comments inside the element-body {}.

  • Put adoc-comments after the element that the comment belongs to.

  • Please do not use standard apostrophes (') inside your comment as this is the comment marker used by plantuml. Use quotation marks (") or acute accents (ยด) instead.

2. Types of documentation comments

2.1. Simple comment /'adoc <text> '/

  • A standard adoc-documentation of an element.

  • The <text> will appear as comment in a value/comment-table.

  • This type is useful to describe enum values and other elements without a special adoc-documentation tag.

Example
enum Example_enum {

    First_value     /'adoc Documentation for "first value" '/
    Second_value    /'adoc Documentation for "second value" '/

}

2.2. Basic comment /'adoc-basic <keyword>: <text> ’/

  • Used to document the basic qualities of a class.

  • Put the <keyword> followed by a colon (without space), followed by a space, followed by the documentation <text>.

  • The following keywords are supported:

    • instantiable
      Yes for normal entities, no for abstract entities.

    • parent
      You may add a parent manually here. Parents are also automatically deduced from the uml file.

    • description
      A description of the entity.

    • controlled_states
      Action-specific information about controlled states.

    • action_ending
      Action-specific information about when exactly an action ends.

    • action_actors
      Action-specific information about which actors use the action.

    • include
      Path to an adoc-fragment. If found, this fragment is added at the end of the description text before the basic information table. Use this option for more sophisticated text formatting with paragraphs, lists and pictures.
      Works best with paths relative to the adoc-output directory.

    • examples
      Path to an adoc-fragment with examples. If found, this fragment is added after the description tables.
      Works best with paths relative to the adoc-output directory.

    • implementation
      Path to an adoc-fragment with implementation details. If found, this fragment is added after the description tables.
      Works best with paths relative to the adoc-output directory.

  • The information forms the basic information table in the fragment.

  • Information about inheritance, composition, aggregation, and connection is automatically retrieved.

Example
class child_class {
    /'adoc-basic instantiable: no'/
    /'adoc-basic parent: parent_class '/
    /'adoc-basic description: This is the child class. '/
    /'adoc-basic controlled-states: Any state. '/
    /'adoc-basic action_ending: Ends when actor reaches destination. '/
    /'adoc-basic action_actors: vehicle, person, animal '/
    /'adoc-basic include: ./path/to/file.adoc '/
    /'adoc-basic examples: ./path/to/example_file.adoc '/
    /'adoc-basic implementation: ./path/to/impl_details_file.adoc '/

}

If the inheritance relationship between elements is expressed in the plantuml using <|-- or <|.. the keyword parent is not needed.

If the keyword parent is used in this case, it overrides the uml relationship.

2.3. Property comment /'adoc-property <type>;<card.>;<desc.> '/

  • Used to document a property.

  • The following specific qualities of a property have to be mentioned, separated by a semicolon:

    • Type

    • Cardinality

    • Description

  • The information forms the table of properties.

Example
class thing {
    center  /'adoc-property double;1..1;Geometrical center '/
    length  /'adoc-property double;1..1;Dimension in x-direction '/
}

2.4. State comment /'adoc-state <state>: <type>;<card.>;<desc.> '/

  • Used to document the states of a class.

  • Put any <state> followed by a colon (without space) followed by a space followed by the following qualities of the state separated by semicolon:

    • Type

    • Cardinality

    • Description

  • This information forms the table of states in the fragment.

Example
class another_class {

    /'adoc-state speed: double;1..1;The speed '/
    /'adoc-state position: double;1..1;The position '/
}

2.5. Method comment /'adoc-method <method_fragment.adoc> '/

  • Used to mark an entry, usually a function as a method.

  • Fragment with detailed description, like return value and arguments.

Example
class yet_another_class {
    do_something()  /'adoc-method ./path/to/fragment/thing_do_something.adoc '/
}

2.6. Modifier comment /'adoc-modifier <modifier_fragment.adoc> '/

  • Used to mark an entry, usually a function, as a modifier.

  • Fragment with detailed description, like description and parameters.

Example
class and_another_class {
    modify_xy()  /'adoc-modifier ./path/to/fragment/thing_modify_xy.adoc '/
}

2.7. Modifier comment /'adoc-antora_targetpage <module:filename> '/

  • Only necessary if linktype: "antora" is set.

  • The links are generated in antora style xref:module:filename[linkname] rather than the default <<anchor, anchorname>>.

  • This comment is necessary to deliver module and filename. These cannot be determined automatically, because they depend on the antora document structure.

3. Keywords and stereotypes

Uml2adoc recognizes and processes the following plantuml keywords:

  • abstract

  • class

  • entity

  • enum

  • interface

Uml2adoc is able to process the following additional information:

  • Color #…​

  • Stereotypes <<…​>>

3.1. Finding the correct names for headings

The headings in the generated fragments need to have the type of the element included.

These are the rules for creating the proper type names:

3.1.1. Stereotype defined

If an element has a stereotype defined, then the stereotype name is used.

This should be the normal case. The capitalization of the stereotype name is changed to match headline requirements.

Example:

class myThing <<ACTOR>> #White { ...

Generated headline: "Actor myThing"

3.1.2. No stereotype defined

If no stereotype is defined, the follwing rules apply:

  1. An abstract is called "Abstract".

  2. A class without adoc-basic controlled_states and adoc-basic action_ending is called "Struct".

  3. A class with adoc-basic controlled_states or adoc-basic action_ending is called "Action".

  4. An entity is called "Actor".

  5. An enum is called "Enum".

  6. An interface is called "Abstract".

This is just a fallback solution that may not be accurate. Check the fragment output.

4. Workflow

4.1. Creating adoc-fragments

Follow these steps to add documentation:

  1. Add adoc-comments to plantuml files.

  2. Commit and push plantuml files to gitlab.

The pipeline then runs the script and adoc fragments are created automatically.

4.2. Excluding files with /'adoc-fileignore’/

If you want to exclude a uml-file from being analyzed, insert /'adoc-fileignore'/ at the beginning of the uml-file.

Example
@startuml foo
/'adoc-fileignore'/
class bar {
...
}
@enduml

4.3. Checking adoc-fragments

If you want to check the content of the created fragments, you can download them as a pipeline artifact. Depending on which Gitlab page you are using you can find the artifacts at different places.

4.3.1. Pipeline CI page

Use the download button on the pipeline continuous integration page.

where to download the artifacts on the CI page
Figure 1. Download option on CI page

4.3.2. Merge request page

Use the download option on the page of the merge request.

where to download the artifacts on the MR page
Figure 2. Download option on MR page

4.4. Using adoc fragments

Once the fragments are available in the pipeline you can use the anchors to link to specific parts or you can include the fragments in your adoc documents.

4.4.1. Linking to adoc fragments

Use the following link syntax in your document to link to details in the fragment:

 <<the-uid-of-the-fragment-detail, A readable descrition of the link destination>>

A link to the anchor 'the-uid-of-the-fragment-detail' is created.

  • The uid of the fragment is
    [#top-<plantuml_name>-<element_type>-<element_name>]

  • The uid of the table with basic information is
    [#tab-<plantuml_name>-<element_type>-<element_name>-basics]

  • The uid of the table with standard and property information is
    [#tab-<plantuml_name>-<element_type>-<element_name>-info]

  • The uid of the table with state information is
    [#tab-<plantuml_name>-<element_type>-<element_name>-states]

4.4.2. Including adoc fragments

You can make the adoc-fragment part of your adoc-topic by including it using the following syntax:

 include::./path/to/fragments/fragment_name.adoc[]

This way the whole fragment appears as if it was copied into your topic.

  • The name of the fragment is
    <plantuml_name>_<element_type>_<element_name>.adoc