[lazarus] Pasdoc compliant comments

[Michael A. Hess]

> Cliff Baeseman wrote:
> 
> Mike or anyone what is the proper format for a pasdoc comment. I am
> coding a unit here and wish to make sure we do not have to revisit it
> for some while.

Simply put the comment that is found just before the object is what is
used by Pasdoc. That object can be a unit, class, class method, class
variable, etc.

There are also several tagged fields to place in the comments that are
useful.

{
@abstract(provides access to file and directory operations)
@author(John Doe <doe at john-doe.com>)
@created(July 12, 1997)
@lastmod(June 20, 1999)
The DOS unit provides functionality to get information on files and
directories and to modify some of this information.
This includes disk space (e.g. @link(DiskFree)), access rights, file
and directory lists, changing the current directory, deleting files
and directories and creating directories.
Some of the functions are not available on all operating systems.
}
unit DOS;

++++++++++++++++++++++

One note. DO NOT put your email address in the standard comment area. If
you do the '@' is taken to be a link and Pasdoc gets unhappy since it
can't find a link of that name. Be sure to only place your email address
in the @author() field as in the example above.

The @link(DiskFree) is exactly what it appears to be. This will create a
hyperlink in the HTML file to the object named DiskFree. So if a
specific unit or class or object has a directly reference to another
unit class or object you might want to place these links in the
comments.

You can also have multiple @author() fields. This way if several
developers work on a unit they can all be listed in the units comment
section. Just place each one in it's own @author() field.

The @abstract() field should just be a simple one liner giving a quick
statement as to the units or classes purpose. This is displayed in the
overview page.

The rest of the fields should be obvious as to what they are. The
remainder of the comment is the used as the primary description of the
object. This can be as long as is required.

You will probably only want to use the whole list of fields shown above
in the units comments. When writting a comment section for a class you
really only need to use

{
@abstract(provides access to file and directory operations)
@author(John Doe <doe at john-doe.com>)
The TMyClass class provides ....
....
....
}
TMyClass = class(TObject)
  .
  .
  .
  .
end;

You can also place comments before each variable in the class and each
method in the class. This will just be the description without any of
the other fields being used.


At this point I would hold off on adding any comments above variables or
methods. The reason is that it gets very cluttered and hard to read. The
current version of Pasdoc does have the feature where in comments can be
pulled from an associated text file. This way we can place the comments
outside of the code and not make the code difficult to read. I have not
tested this feature yet but plan to do so in the next several days.

If we just place comments before units and class this alone will be a
very big improvement. Please note that if you place ANY comments before
a unit or class it will be used by Pasdoc as it's description. So for
example if a copyright notice is at the top of the unit but no other
comment is placed before the unit line then that copyright becomes the
description in the documentation. To stop this be sure to place a set of
comment characters, the {..} characters before the unit line either with
or without any information between them.  :-)

-- 
==== Programming my first best destiny! ====

Michael A. Hess      Miracle Concepts, Inc.
mhess at miraclec.com   http://www.miraclec.com