3.5 Documenting Elements

We now have to add an Element block for each identifier we want to document.

Here are the two possible simplifed formats for an Element block (see Structure of an Element for the full format).

The first possible format is:

      Element: Name [-- ShortDescription]
     
      [LongDescription]

The second possible format is:

      Element: Name
     
      [ShortDescription]
     
      [LongDescription]

Below is an example of documentation for the Max function and its arguments A and B.

     Example: Documenting Max  
      1  Package: MyPkg
      2
      3  Module: MyUnit
      4
      5    MyUnit contains some essential routines.
      6
      7    This routines are the result of many years of
      8    hard work.
      9
     10    I hope they will help to save mankind.
     11
     12  Element: Max -- Return largest of two values.
     13
     14    Max returns the maximum of A and B.
     15
     16  Element: Max.A -- first value
     17
     18  Element: Max.B -- second value
     19
     20  End Module: MyUnit
     21
     22  End Package: MyPkg

• Documentation for function Max starts in line 12 with a short description (line 12) and a long description (line 14).
• Documentation for parameter A of Max is in line 16.
• Documentation for parameter B of Max is in line 18.