This guide shows how to add documentation comments (short: adoc-comments) to plantuml-files that will then be 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 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

    • parent

    • description

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

Example
class Child_class {
    /'adoc-basic instantiable: no'/
    /'adoc-basic parent: Parent_class '/
    /'adoc-basic description: This is the child class. '/
}

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

  • Used to document a property.

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

    • Type

    • Cardinality

    • Relationship

    • 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.>;<rel.>;<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

    • Relationship

    • Description

  • The 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 '/
}