3.4 Adding Descriptions

Almost all the elements that we can document can have a short description and a long description. So let's add descriptions to the module MyUnit.

     Example: First descriptions  
      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  End Module: MyUnit
     13
     14  End Package: MyPkg

The short description is the first paragraph following the header line (line 5). It ends on the blank line (line 6). Then, all following paragraphs (lines 7-10) are part of the long description.

Short descriptions can also start on the header line, after a double hyphen (‘--’).

     Example: Short description on header line  
      1  Module: MyUnit -- MyUnit contains some essential
      2    routines.

Short and long descriptions can be beautified by the use of some markups (see Beautifiers).

     Example: Descriptions with beautifiers  
      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  End Module: MyUnit
     13
     14  End Package: MyPkg

• 'MyUnit' (line 5) will be emphasized.
• 'hard work' (line 8) will be rendered bold.

See Descriptions for more information on descriptions.