Next: , Previous: Abbreviated Syntax, Up: Documenting Your Code


3.12 Composite Types

     Example: An example class  
      1  type
      2    TRectangle = class
      3    private
      4      fHeight: Real;
      5      fWidth: Real;
      6    public
      7      constructor Create(W, H : Real);
      8
      9      function Area : Real;
     10      procedure SetSize(W, H : Real);
     11
     12      property Height : Real read fHeight write fHeight;
     13      property Width : Real read fWidth write fWidth;
     14    end;

Suppose you want to document the TRectangle class above. You can do it like we have learn to do it until now.

     Example: TRectangle documentation  
      1  Type: TRectangle -- A class that implements a rectangle.
      2
      3  Constructor: TRectangle.Create -- Creates a new rectangle.
      4
      5    Parameters:
      6      - W -- width
      7      - H -- height
      8
      9  Function: TRectangle.Area -- Returns the rectangle area.
     10
     11  Procedure: TRectangle.SetSize -- Sets the rectangle size.
     12
     13    Parameters:
     14      - W -- width
     15      - H -- height
     16
     17  Property: TRectangle.Height -- rectangle height
     18
     19  Property: TRectangle.Width -- rectangle width

Alternatively you can choose to use Struct/End Struct headers and there synonyms.

     Example: TRectangle documented with Struct  
      1  Struct: TRectangle -- A class that implements a rectangle.
      2
      3    Constructor: Create -- Creates a new rectangle.
      4
      5      Parameters:
      6        - W -- width
      7        - H -- height
      8
      9    Function: Area -- Returns the rectangle area.
     10
     11    Procedure: SetSize -- Sets the rectangle size.
     12
     13      Parameters:
     14        - W -- width
     15        - H -- height
     16
     17    Property: Height -- rectangle height
     18    Property: Width -- rectangle width
     19
     20  End Struct: TRectangle

All elements documented between Struct (line 1) and End Struct (line 20) are considered as sub elements of TRectangle. The closing End Struct is mandatory.

Of course you can also use synonyms of Struct/End Struct, like Class/End Class, and mix documentation and code.

     Example: TRectangle documented in source code with Class  
      1  type
      2    {** Class: TRectangle -- A class that implements a rectangle. }
      3    TRectangle = class
      4    private
      5      fHeight: Real;
      6      fWidth: Real;
      7    public
      8      {** Constructor: Create -- Creates a new rectangle.
      9
     10          Parameters:
     11            - W -- width
     12            - H -- height }
     13      constructor Create(W, H : Real);
     14
     15      {** Function: Area -- Returns the rectangle area. }
     16      function Area : Real;
     17
     18      {** Procedure: SetSize -- Sets the rectangle size.
     19
     20          Parameters:
     21            - W -- width
     22            - H -- height }
     23      procedure SetSize(W, H : Real);
     24
     25      {** Property: Height -- rectangle height }
     26      property Height : Real read fHeight write fHeight;
     27
     28      {** Property: Width -- rectangle width }
     29      property Width : Real read fWidth write fWidth;
     30    end; {** End Class: TRectangle}