Mike or anyone what is the proper format for a pasdoc comment. I am coding a unit here…
Show quoted text 5 lines
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 )
@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 )
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. :-)