Basic rule

If you want to assign some description to your item (where item means either a unit, a class, a field, a method, a variable, a type, a constant, a function or procedure... really, just anything), you just place a comment directly before the item's declaration.

Here's an example of a complete unit with many items documented:

   1 { Description of MyUnit. }
   2 unit MyUnit;
   3 
   4 interface
   5 
   6 type
   7   { Description of TMyClass. }
   8   TMyClass = class
   9   public
  10     { Description of MyField. }
  11     MyField: Integer;
  12     { Description of MyMethod. }
  13     procedure MyMethod;
  14   end;
  15 
  16   { Description of TMySimpleType. }
  17   TMySimpleType = 1..100;
  18 
  19   { Description of TMyEnumType. }
  20   TMyEnumType = (
  21     { Description of meFirstValue. }
  22     meFirstValue,
  23     { Description of meSecondValue. }
  24     meSecondValue);
  25 
  26 const
  27   { Description of MyConstant. }
  28   MyConstant = 4;
  29 
  30 var
  31   { Description of MyVariable. }
  32   MyVariable: Integer;
  33 
  34 { Description of MyProcedure. }
  35 procedure MyProcedure;
  36 
  37 implementation
  38 ...
  39 end.

You can simply paste the above example into a file like myunit.pas and run pasdoc like this

pasdoc myunit.pas

and pasdoc will generate the documentation for MyUnit (in the default HTML format). All the "Description of ..." comments are nicely shown in the resulting documentation.

More detailed rules

Comment markers

You can use --marker option if you want PasDoc to recognize only comments designated by some special markers.

Multiple fields/variables in one declaration

The case when you declare multiple fields/variables with the same type in one declaration deserves some detailed explanation. This concerns declarations like this:

   1 type
   2   TMyRecord = record
   3     { Comment 1 }
   4     Field1, Field2: Integer;
   5   end;
   6 
   7 var
   8   { Comment 2 }
   9   Variable1, Variable2: Integer;

The rule is as follows: it is assumed that the single comment will apply to all multiple fields in the following declaration. So in the example above, Comment 1 will be understood to document both Field1 and Field2 and Comment 2 will be understood to document both Variable1 and Variable2.

Moreover, if you place a comment in the middle of such multiple-declaration, this comment will apply to all following fields/variables within this declaration. See this example:

   1 type
   2   TMyRecord = record
   3     { This comment documents Field1 and Field2 }
   4     Field1, Field2,
   5       { This comment documents Field3 and Field4 }
   6       Field3, Field4: Integer;
   7   end;
   8 
   9 var
  10   { This comment documents Variable1 }
  11   Variable1,
  12     { This comment documents Variable2 }
  13     Variable2: Integer;

Placing comments after the item

Sometimes it is more convenient to place your documentation comment after the documented item, instead of before. You can freely do so by placing the "<" ("less-than") character as the exactly first character of your comment. This tells PasDoc that the given comment should be assigned to the preceeding (not the following, as usual) item declaration.

Example:

   1 unit MyUnit;
   2 
   3 {< Here you can place a description of MyUnit. 
   4    This is convenient for people that like to always 
   5    keep the "unit UnitName;" declaration 
   6    as the first line of their *.pas files. }
   7 
   8 interface
   9 
  10 type
  11   TMyEnumType = (
  12     meOne, //< Description of meOne
  13     meTwo, //< Description of meTwo
  14     meThree //< Description of meThree
  15   );
  16 
  17   TMyClass = class
  18     MyField: Integer; //< Description of MyField
  19     procedure MyProc; //< Description of MyProc
  20     property MyProp: Integer read MyField write MyField; 
  21       //< Description of MyProp
  22   end;
  23 
  24   TMyException = class(Exception); //< Description of TMyException
  25 
  26 var
  27   SomeVariable: Integer; //< Description of SomeVariable
  28   Var1, Var2: Integer; //< Description of Var1 and Var2
  29 
  30 implementation
  31 ...
  32 end.

If you use a CommentMarker, the "<" character must be placed right after your chosen marker.

Glueing single-line comments

Subsequent //-style comments are "glued" by pasdoc into one comment. For example these two methods of documenting procedure Foo are equivalent:

   1 { This is
   2   description of
   3   procedure Foo. }
   4 procedure Foo;
   5 
   6 // This is
   7 // description of
   8 // procedure Foo.
   9 procedure Foo;

Common case when comments are not meaningfull to PasDoc

As long as we consider only multi-line comments ({}-style or (**)-style), remember that pasdoc takes into account only the last comment before given item. For example, in the code below, comment Ignored comment is ignored by pasdoc. Description consists only of Description of Foo comment.

   1 { Ignored comment. }
   2 
   3 { Description of Foo. }
   4 procedure Foo;

In particular, note that when you want to hide some comment (i.e. prevent it from being assigned to the next item) all you have to do is to put "{ }" (empty comment) right before given item. For example:

   1 { procedure Foo; }
   2 
   3 { }
   4 procedure Bar;

In the above example, programmer probably temporarily commented out procedure Foo; declaration. To prevent from accidentaly assigning description "procedure Foo;" to procedure Bar, the programmer added "{ }" right before procedure Bar declaration.