Pasdoc creates documentation for Pascal unit files.
Descriptions for variables, constants, types (called ’items’ from now on) are taken from comments stored in the interface sections of unit source code files, each comment must be placed directly before the item’s declaration.
This way, you as a programmer can easily generate reference manuals of your libraries without having to deal with the details of document formats like HTML or LATEX.
Moreover, you can edit the source code and its descriptions in one place, no need to add or modify explanations in other files. The rest is done automatically, you should write a script / batch file that does the actual call to pasdoc... Download the latest version from
http://pasdoc.sourceforge.net.
|
For an example of source code that can be used with pasdoc, try the pasdoc sources themselves - type pasdoc[.exe] --format html *.pas to generate HTML documentation.
You can compile pasdoc with Free Pascal (version 1.0 or higher), as well as with Delphi and Kylix.
As you may know, Pascal allows for directives in the source code. These are comments that contain commands for the compiler introduced by the dollar sign.
To distinguish different compilers, libraries or development stages, conditional directives make it possible to make the compiler ignore part of the file. An example:
unit SampleUnit;
{$ifdef WIN32} uses Windows, WinProcs; procedure WindowMove(H: TWindowHandle; DX, DY: Integer); procedure WindowPrintText(H: TWindowHandle; X, Y: Integer; S: String); {$else} procedure ClearConsole; procedure PrintText(S: String); {$endif} {$define DEBUG} {$undef OPTIMIZE} |
The ifdef part checks if a conditional directive called WIN32 is currently defined (that would be the case for Delphi or FPC/Win32). If this is true, all code until else or endif are compiled, everything between else and endif is ignored. The contrary would apply if the directive is not defined, e.g. under FPC/DOS or Borland Pascal. These statements can also be nested. Using define and undef, a programmer can add and delete directives, in the above example DEBUG and OPTIMIZE.
As pasdoc loads Pascal files in a similar way a compiler does, it must be able to regard conditional directives. All define and undef parts are evaluated by pasdoc, modifying an internal list of directives as source code is parsed.
Different from a real compiler, pasdoc starts with an empty list of conditional directives. To get back to the above example, if you want to write documentation for the WIN32 code part, you must explicitly tell pasdoc that you want this directive defined.
You can do so using the Specify directive or Add directives from file switch (see sections 5.5.6 and 5.5.8).
Next to those directives already presented, pasdoc also supports include files:
type TInteger = Integer;
{$I numbers.inc} const MAX_FILES = 12; |
In the above code, pasdoc would parse TInteger, get the include directive and start parsing the include file numbers.inc. This file could contain other directives, types or whatever. It is treated as it would be treated by any Pascal compiler.
Pascal compilers also know switch directives. These are boolean options, either on or off. They can be checked similar to conditional directives with the $ifopt directive. Pasdoc does not yet fully support these, but at least does not give up when it encounters one.
You can provide documentation for
Providing a description for the different items is fairly easy. You simply need to provide a comment containing the description before the name of the item itself.
For units, the comment declaration must be done before the unit keyword. Example:
type
{ This record type stores all information on a customer, including name, age and gender. } TCustomer = record Name: String; Age: Byte; Gender: Boolean; end; { Initializes a TCustomer record with the given parameters. } procedure InitCustomer(Name: String; Age: Byte; Gender: Boolean; var Customer: TCustomer); |
It is possible to specify that items will only be documented when certain comment markers are present at the start of the comment. Please refer to 5.3 for further information. Furthermore, undocumented items may or may not appear in the final document, depending on the output format.
An interesting feature of pasdoc is its ability to link items from within comments. If you are currently writing about an array of integers TIntArray you’ve declared as a type, you might mention that the number of values it can store is specified in the constant MAX_INTS. You’ve probably already documented this constant when you declared it earlier in the same or another unit. Now, if you write @link(MAX_INTS) instead of simply MAX_INTS, pasdoc knows that you are referring to another item it has found or will find in the list of units you gave to it. After all input files have been parsed, pasdoc will start substituting all occurrences of @link(something) with ”real” links. Depending on the type of output, these links could be hyperlinks (in HTML) or page references (in LATEX). If the current output format is HTML, the description of TIntArray would contain a link to MAX_INTS. Viewing TIntArray’s description in your favourite web browser you’d now be able to click on MAX_INTS and the browser would jump to the definition of MAX_INTS, where you’d find more information on it.
If pasdoc cannot resolve a link (for whatever reasons), it will issue a warning to standard output and will write the content of @link() to the documentation file, not as a link, but in a special font.
All comments recognize special directives that are used for different purposes. Each of these special directives starts with the at character @, followed by and identifier and optinally followed by text between parentheses.
As an example, lets take the well-known DOS unit. Its top part could look like this:
{
@abstract(provides access to file and directory operations) @author(John Doe <doe@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; |
Pasdoc would read this comment and store it with the unit information. After all Pascal source code files you gave to pasdoc have been read, pasdoc will try to process all tags, i.e., all words introduced by a @ character.
If you want to use the character @ itself, you must write it twice so that pasdoc knows you don’t want to specify a tag.
Note in the example above that the character does not need this special treatment within the parentheses, as shown in the author tag at the example of the email address.
Following is a list of all tags that you may use in pasdoc. A tag like @link must always be followed by an opening and then a closing parenthesis, even if you add nothing between them.
The following tags are supported:
Represents the @ character, for example if you want to use one of the tags literally
For some item types like classes or units you may write very large descriptions to give an adequate introduction. However, these large texts are not appropriate in an overview list. Use the abstract tag to give a short explanation of what an item is about. One row of text is a good rule of thumb. Of course, there should only be one abstract tag per description.
The abstract text will appear in the overview section of the documentation (if the document format supports this overview section), and will also appear as the first paragraph of the item full documentation.
For each author who participated in writing an item, one author tag should be added. The format of the author tag should conform to the following specification : @author(Name <URI>)
Author tags will only result in documentation output for classes, interfaces, objects and units.
Example:
@author(Johannes Berg <email@address.here>)
|
PasDoc uses the tags @inherited, @classname and @name as placeholders for the names of the ancestor class, current class and name of the current item respectively.
Example:
{ @name is a method of @classname which overrides the method of @inherited to do something completely different...} |
PasDoc uses the tag @code to mark example code which is preformatted and should not be changed in the output. It will usually appear in a teletype font in the final documentation.
Example:
{: how to declare a variable.
Example: @code( var SomeVariable: SomeType;) } |
This tag should contain the date the item was created. At most one created tag should be in a description. Created tags will only result in documentation output for classes, interfaces, objects and units. There is no special format that must be followed.
This tag is used to extract the last modification date and authors of the item. The parameter of this tag should conform to the Author : ccodere or Date : 2004/04/2002 : 01 : 52 string of cvs or rcs.
@cvs($Date: 2004-04-20 04:02:54 +0200 (Tue, 20 Apr 2004) $)
|
If an exclude tag is found in a description, the item will not appear in the documentation. As a logical consequence, no information except the exclude tag itself should be written to the description. Whenever high-level items like units or classes are excluded from the documentation process, all items contained in them will not appear as well, e.g. constants or functions in an excluded unit or methods and fields in an excluded class.
The following example will produce no documentation, as the entire unit will be excluded from the documentation process.
Example:
{@exclude }
unit myunit; interface procedure hello; implementation procedure hello; begin WriteLn('Hello'); end; end. |
PasDoc inserts the specially formatted text ’false’ here at the location of the tag. This tag does not have any parameters.
Pasdoc directly outputs the text that is between parentheses, without any conversion for the html output format. For other formats, the text is converted to standard text.
There is no syntax checking on the validity of the HTML syntax.
If there are no parentheses, @HTML is directly written to the output documentation.
This tag should contain the date the item was last modified. At most one created tag should be in a description. Lastmod tags will only result in documentation output for classes, interfaces, objects and units. There is no special format that must be followed.
Use this tag to make your documentation more convenient to the reader.
Whenever you mention another item in the description of an item, enclose the
name of the mentioned item in a link tag, e.g.
@link(GetName).
This will result in a hyperlink in HTML and a page reference in LATEX.
Use this tag to output code, and pre-formatted text. The output text will closely ressemble the text typed, and will be represented in a fixed width font. In the case of pascal code typed within this tag, it will be pretty-printed first.
To be able to put special characters in this tag, the tag should be followed by a # and finished with a # before the closing parentheses.
Example:
@longCode(#
procedure TForm1.FormCreate(Sender: TObject); var i: integer; begin // Note that your comments are formatted. {$H+} // You can even include compiler directives. // reserved words are formatted in bold. for i := 1 to 10 do begin It is OK to include pseudo-code like this line. // It will be formatted as if it were meaningful pascal code. end; end; #) |
PasDoc inserts the specially formatted text ’nil’ here. This tag does not have any parameters.
Treats first argument as parameter name and all following text as the description of this parameter.
Example:
{ A small description
@param(Filepath The file to open) } constructor Init(FilePath : String); |
Treats the first argument as exception name and all following text as the description for this exception.
Example:
{ A small description
@raises(EMyException Raises this exception) } constructor Init; |
Treat the text in the argument as the description of the returns value of this function or method.
PasDoc inserts the specially formatted text ’true’ here at the location of the tag. This tag does not have any parameters.
This is a list of all switches (program parameters) supported by pasdoc. Enter pasdoc --help at the command line to get this list. Make sure you keep the exact spelling of the switches, pasdoc is case-sensitive. Most switches exist in two variations, a short one with a single dash and a longer one with two dashes. You can use either switch to get the same effect.
After loading all Pascal source code files, pasdoc will write one or more output files, depending on the output file format. Choose the output format according to your needs - you might want to create several versions for
-O html
--format html
This switch makes pasdoc write HTML (Hypertext Markup Language) output. HTML files are usually displayed in a web browser, which available on all modern computer systems.
It is the default output file format. Several files will be created for this output type, one for each unit, class, interface and object, additionally some overview files with lists of all constants, types etc.
This is the preferred output for online viewing.
It is to note that even undocumented items will appear in the final output file format.
-O htmlhelp
--format htmlhelp
This switch makes pasdoc write HTML (Hypertext Markup Language) output. It also writes additional files that can be used to create Microsoft htmlhelp files. Please consult the htmlhelp Microsoft SDK for more information.
-O latex
--format latex
This switch makes pasdoc write output that can be interpreted using LATEX. This is the preferred output format for printing the documentation.
A single output file, either having the name specified with the -N switch, or the default name docs.tex will be created.
With latex you will be able to create a dvi file that can then be converted to a Postscript file using dvips. Or you can also directly generate a huge HTML file by using htlatex, or a PDF file by using pdflatex.
It is to note that the output generated by pasdoc has been optimized for pdflatex and htlatex.
It is to note that only documented items will appear in the final output file format.
-O latex2rtf
--format latex2rtf
This switch makes pasdoc write output that can be interpreted using latex2rtf. This is the preferred output format for adding the documentation to word processor documentation.
A single output file, either having the name specified with the -N switch, or the default name docs.tex will be created. This file can then be converted to rtf by using latex2rtf.
This output will only work with the latex2rtf tool. Using other tools might not produce the expected results.
It is to note that only documented items will appear in the final output file format.
The following switches can only be used with one output file format and are useless for the others.
-X
--exclude-generator
By default, pasdoc includes some information on itself and the document creation time at the bottom of each generated HTML file. This switch keeps pasdoc from adding that information.
-N NAME --name NAME
When the output format of the documentation is not HTML (such as latex, or CHM), this specifies the name of the final name of the documentation. If this is not specified, it uses the defaultdocs filename.
-F FILNAME --footer FILENAME -H FILNAME --header FILENAME
You can specify texts files which PasDoc should use as header or footer for all generated html pages. This option is only available for the html output format.
Example:
pasdoc --header myheader.txt --footer myfooter.txt
|
It is possible for pasdoc to ignore comments that do not start with the correct start markers. By default, all comments are treated as item descriptions. This can be changed using the following switches:
-L lg
--language lg
You can specify the language that will be used for words in the output like Methods or Classes, interfaces and objects. Your choice will not influence the status messages printed by pasdoc to standard output - they will always be in English. Note that you can choose at most one language switch - if you specify none, the default language English will be used.
The lg parameter can take one of the following values:
-M
--visible-members
By default all non-private fields, methods properties are included in the documentation. This switch permits to change which items of the specified visibility will be documented.
The possible arguments, separated by a comma are:
In the following example only the private and protected members will be documented, all others will be ignored.
pasdoc --visible-members private,protected
|
-E DIRECTORY
--output DIRECTORY
By default, pasdoc writes the output file(s) to the current directory. This switch defines a new output directory - this makes sense especially when you have many units and classes, they should get a subdirectory of their own, e.g. htmloutput.
-S FILE
--source FILE
If you want pasdoc to write documentation for a large project involving many unit source code files, you can use this switch to load the file names from a text file. Pasdoc expects this file to have one file name in each row, no additional cleaning is done, so be careful not to include spaces or other whitespace like tabs.
-v LEVEL
--verbosity LEVEL
Using this switch in combination with an integer number > 0 lets you define the amount of information pasdoc writes to standard output. The default level is 2, this switch is optional. A level of 0 will result in no output at all.
-?
--help
This switch makes pasdoc print usage hints and supported switches to standard output (usually the console) and terminates.
-D DIRECTIVE
--define DIRECTIVE
Adds DIRECTIVE to the list of conditional directives that are present whenever parsing a unit is started.
The list of directives will be adjusted whenever a directive like WIN32 or FPC is defined or undefined in the source code. Each define should be separated by the others by a comma, as shown in the following example:
pasdoc --define debug,hello,world
|
-I DIR
--include DIR
Adds DIR to the list of directories where pasdoc will search for include files. Whenever an include file directive is encountered in the source code, pasdoc first tries to open that include file by the name found in that directive. This will work in all cases where the current directory contains that include file or when the file name contains a valid absolute or relative path.
It is possible to use this switch more than once on the command line.
pasdoc --include c:\mysources\include --include c:\3rdparty\somelib\include
|
-d DIRECTORY
--conditionals DIRECTORY
Adds the defines specified in a file DIRECTORY to the list of conditional directives that are present whenever parsing a unit is started.
The list of directives will be adjusted whenever a directive like WIN32 or FPC is defined or undefined in the source code. There should be one defibe per line in the conditional file.
pasdoc --conditionals /home/me/pascal/myconditionals
|
-T "STRING"
--title "STRING"
This option sets the title of the output document. The characters in the title should be enclosed in double quotes.
By default, depending on the documentation format, the document contains either no title, or the name of the unit being documented.
Example:
pasdoc -T "This is my document title"
|
--write-uses-list
PasDoc can optionally include the list of units in a unit’s uses clause to that unit’s description.
Example:
pasdoc --write-uses-list
|
If a unit in the uses list is part of the documentation, it will be clickable in the output.
By default this option is disabled.
--full-link
This option controls the behaviour of ”@link(unit.procedure)” type links. If it is set, the output generated will look like this:
unit.procedure with the ”unit” part linking to the unit and the ”procedure” part linking to the procedure inside the unit. If it is unset, then the output will only be procedure.
This lists the other unusual switches that are recognized by pasdoc:
As was said before, only units are regarded by pasdoc. In an OOP environment for which pasdoc was written, an application is usually a class overriding an abstract application class, so all code that is ever needed in the program file looks like this:
program main;
uses myapp; var App: TMyApplication; begin App := TMyApplication.Create; App.Run; App.Destroy; end. |
So there isn’t much to do for documentation. If you’re not using OOP, you could at least try to move as much code as possible out of the main program to make things work with pasdoc.
Pasdoc cannot create separate documentation for members of a record. In object-oriented programs, records will not appear most of the time because all encapsulated data will be part of a class or object. However, you can give a single explanation on a record type which could contain a description of all members.
In some larger projects, identifiers may be used in different contexts, e.g. as the name for a parameter and as a function name. Pasdoc will not be able to tell these contexts apart and as a result, will create in the above-mentioned example links (at least in HTML) from the argument name of a function to the type of the same name.
If you want to write a different type of document than those supported, you can create another unit with a new object type that overrides TDocGenerator from unit PasDoc_Gen.pas. You’ll have to override several of its methods to implement a new output format. As examples, you can always look at how the HTML and LATEXgenerators work. First of all, you must decide whether your new output format will store the documentation in one (like LATEX) or multiple files (like HTML).
Thanks to Michael van Canneyt, Marco van de Voort, Dan Damian, Philippe Jean Dit Bailleul, Jeff Wormsley, Johann Glaser, Gudrun Plato, Erwin Scheuch-Hellig, Iván Montes Velencoso, Mike Ravkin, Jean-Pierre Vial, Jon Korty, Martin Krumpolec, André Jager, Samuel Liddicott, Michael Hess, Ivan Tarapcik, Marc Weustink, Pascal Berger, Rolf Offermanns and Rodrigo Urubatan Ferreira Jardim for contributing ideas, bug reports and fixes, help and code!