Overview

PasDoc is a documentation tool for ObjectPascal source code. Documentation is generated from comments found in source code. See WhereToPlaceComments, WritingDocumentation and SupportedTags for information on how to document your source code.

Available output formats are HTML, HtmlHelp, LaTeX, latex2rtf, simplexml. More output formats may be added in the future.

Check out the CommandLine to get a better feeling for how PasDoc works. There is also a GUI interface, see PasDocGui.

Check out PasDocAutoDoc and ProjectsUsingPasDoc to see some real-world examples of how documentation generated by PasDoc looks like, and to see some programs that use PasDoc's code.

You may also be interested in the list of AdvancedFeatures of PasDoc.

Download

Download stable PasDoc releases at Sourceforge download page.

Send feedback

If you are missing anything, add it to the WantedFeatures list, alternatively see the ToDo list for things that need to be done in the current code. Furthermore, there is a dream document for PasDoc2.

Everyone is welcome to subscribe to the pasdoc-main mailing list to discuss pasdoc features, contribute patches, or report bugs. A list archive is also available.

You can also use the trackers to report bugs, feature requests or submit patches.

Development

See the ChangeLog for recent changes to PasDoc and a short history overview.

If you want to get the newer version of PasDoc but yout don't want to compile PasDoc yourself, you can try DevelopmentSnapshots.

PasDoc source code:

PasDoc is licensed under the GNU General Public License.
You can download up-to-date PasDoc sources from SVN. In short, just call
- ```
svn co https://pasdoc.svn.sourceforge.net/svnroot/pasdoc/trunk
```
See CompilingPasDoc for instructions how to compile PasDoc.

While developing PasDoc we also developed some OtherTools that you may find useful.

About these web pages:

We are using MoinMoin wiki for these pages to be able to update them easily. You are invited to contribute to the documentation, see WikiIntroduction.
All text within this wiki is licensed on terms of GNU General Public License (just like PasDoc sources).
A snapshot of this wiki (including all page history) is generated nightly at 3:10 UTC.

All project services are provided by SourceForge .

Command-line option --format html (or -O html in short) makes pasdoc write HTML (Hypertext Markup Language) output. HTML files are usually viewed using web browsers, 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.

Some details about HTML output:

Contents

CSS
HTML standard conformance

CSS

The look of HTML output is controlled by CSS code in pasdoc.css file, generated by pasdoc while making HTML output. You can customize how your documentation looks by modifying this file. See W3C resources about CSS. See also example alternative CSS styles for pasdoc that you can use.

HTML standard conformance

Html output produced by pasdoc is completely valid HTML 4.01 Transitional format. See W3C HTML 4.01 Specification.

You can validate it using any html validator. In case you never used html validator:

W3C online validator is handy if you don't want the trouble of installing anything on your computer.
There's also excellent standalone validator nsgmls. It's part of the SP suite. Debian users should be able to install it simply by installing package named sp.
A fork of SP suite is developed by project OpenJade. It's named OpenSP. nsgmls is renamed inside this suite to onsgmls. Debian users should be able to install it simply by installing package named opensp. Windows users should be able to install it as a cygwin package OpenSP.
onsgmls is used by pasdoc's automatic tests (inside tests/ subdirectory), so this is somewhat a "validator of choice" for us.
Emacs users can also use validator included in Emacs html mode (M-x sgml-next-trouble-spot, standard shortcut is C-c C-o).
Of course, this list doesn't try to be exhaustive. There are many more html validators out there.

HTML Help (extension .chm for "compiled html") is the help format for recent versions of Windows.

PasDoc can generate the files that are needed in addition to the HTML output to use the Microsoft HTML Workshop (free download) for creating HTML Help.

See http://msdn.microsoft.com/workshop/author/htmlhelp/ for more information on HTML Help.

Short introduction how to use htmlhelp output:

[Optional] If you wish to use a custom help-contents file, specify a file name with the html-help-contents option. Each line of the file specifies an entry in the help contents. Each space or tab character at the beginning of a line increases the level of the item in the contents by 1. The remainder of the line comprises a title for the item, an "=" character, and the link to which the item should be connected. For example: An Item = MyPage.html
Generate htmlhelp documentation with pasdoc with --format=htmlhelp. In addition to normal html files, pasdoc will also output three files docs.hhc, docs.hhk and docs.hhp. You can change docs to something else with --name option.
Download HTML Help Workshop
Make docs.chm file:
- Interactively: run installed Html Help Workshop, open generated docs.hhp file, run "Compile HTML file" from toolbar
- Or in batch mode: run hhc docs.hhp
And you have docs.chm file, that can be viewed with Html Help viewer.

CommandLine option --format latex (or -O latex for short) 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 --name option, 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.

Notes about warnings displayed by latex and/or pdflatex when they process file generated by pasdoc:

Reference ...' on page ... undefined on input`:

This warning is valid to occur during the first run of latex/pdflatex on the given .tex file. This happens when reference to an item has been made before a label was defined. This is how labels/references in LaTeX work: you must run latex/pdflatex once again, and this time all references should be resolved and no such warning should appear. This is not something that can be corrected inside pasdoc.

Label ...' multiply defined`:

This warning happens when you used in your source file overloading, i.e. defined global functions/procedures with the same name in the same unit or within the same class. Currently pasdoc does not handle this situation absolutely correctly, and labels and references to every version of overloaded routine will look the same. Also, note that currently there is no way in pasdoc to specify within @link tag to which one of the overloaded versions you want to link. So, yes, this is a problem in pasdoc, but not specific to LaTeX output, and requires more general treatment. So far noone implemented this. But this of course does not mean that you can't use overloading in units processed by pasdoc. Pasdoc wil generate a valid and working documentation for overloaded routines, in every output format. You just don't have such control over links to overloaded things as you should have.

When you run pasdoc with CommandLine option --format=latex2rtf you will get docs.tex file suitable for processing with latex2rtf.

This is very similar to normal LatexOutput but a little simplified (because latex2rtf can't handle many advanced features of TeX). Note that the generated docs.tex file cannot be processed by normal latex tools (like latex or pdflatex) because we had to remove some things crucial for normal latex tools. So

if you want to process your file by latex or pdflatex you must use LatexOutput (--format=latex).
if you want to process your file by latex2rtf you must use latex2rtf output (--format=latex2rtf).

Problem with links

Problem

Links in RTF file generated by latex2rtf will not work out of the box. If you generate docs.tex file using

pasdoc --format=latex2rtf ...

and then you will try to process it with latex2rtf using

latex2rtf docs.tex

latex2rtf will print a warning

docs.tex:102 Cannot open <docs.aux>
docs.tex:102 No .aux file.  Run LaTeX to create docs.aux

and generated docs.rtf file will have invalid links ((?) will be displayed where section numbers like (6.3) should be).

Solution

Like instructed by latex2rtf, you must first generate docs.aux using one of normal latex tools. E.g. use the following set of commands:

# Make docs.tex usable with latex
pasdoc --format=latex --output=latex/ ...

# Make latex/docs.aux file
cd latex/
latex docs.tex
cd ../

# Make docs.tex usable with latex2rtf
pasdoc --format=latex2rtf --output=latex2rtf/ ...

# Make docs.rtf using latex/docs.aux file
cd latex2rtf/
latex2rtf -a ../latex/docs.aux docs.tex

Other latex2rtf warnings

No solution. Just ignore them, it's normal. We could probably make them disappear by modifying latex2rtf output format, but it would complicate latex generator code without much gain.

Pasdoc extracts documentation from the comments that you place in your source code. Basically, you just place a description of each item in the comment right before this item's declaration. See WhereToPlaceComments for more detailed explanation. Below you can find a detailed overview how pasdoc interprets some special things in your comments.

Contents

Special features in your comments
Items without documentation

Special features in your comments

Expanding @-tags

See SupportedTags.

Whitespace

Like in HTML or LaTeX, amount of whitespace you put between words (spaces , tabs, newlines) does not matter. In all output formats text will be automatically broken into lines basing on things like web browser window width (e.g. in case of browsing html output in web browser) or page width (e.g. in case of pdf or ps files generated from latex file). E.g. following two documentation comments are equivalent:

```
   1 { This
   2   is
   3   documentation          for           my             class
   4   with a lot of silly whitespace. }
   5 TMyClass = class
   6 ...
```
and
```
   1 { This is documentation for my class with a lot of silly whitespace. }
   2 TMyClass = class
   3 ...
```

Paragraphs

Like in LaTeX: The only exception to the rule above is that an empty line (i.e. newline + some whitespace + newline) means "start new paragraph". More than one empty lines in a row are equivalent to one empty line (in other words, you can't make the gap between two paragraphs larger by inserting more empty lines between them).

Example:
```
   1 { 1st paragraph.
   2 
   3   2nd paragraph. }
   4 TMyClass = class
   5 ...
```

Dashes

Three consecutive dashes, ---, in your comment produce em dash (a long dash used to separate sentence parts — like this). Two consecutive dashes, --, produce en dash (a medium dash used to separate ranges, like 10–20). A single dash character produces just a short dash (good for compound words, like in "variable-width font"). This is similar to LaTeX and Texinfo syntax (but of course it's supported for all pasdoc output formats, including HTML).

You can always write @- to force inserting a short dash. E.g. if you write @-@- then you will get just two consecutive short dashes in the output (instead of an en dash that would be generated for --). Actually, you can just write @-- (because this way you force the first dash to just produce the short dash in the output, and so the 2nd dash is a "single dash", so it will also produce a short dash).

Automatic recognizing of URLs

Pasdoc automatically recognizes URLs (like http://pasdoc.sourceforge.net/) in your comments and appropriately presents them in the output format, so that user reading generated documentation is able to easily navigate to given URL. E.g. in case of HtmlOutput URLs will be converted to links <a href="...">...</a>. In case of LatexOutput URLs will be presented with \html command.

Items without documentation

Note that even undocumented items (that you did not annotate with any comment pasdoc could use) should be visible in every output format. Previously LatexOutput omitted such undocumented things, but now it doesn't. Here's some reasoning why every output format should show everything:

I want to see documentation at least stating that some item exists, if there is no description for it. So all items should be documented, even those without any description attached. If I want to exclude some item I can always use @exclude tag.
It makes links broken, since I can link from some item's description using @link() to an item that has no description. And I want to be able to make such links, to show user how some item is declared and in case I will attach some comment to it in the future.

Tags can be categorized into 3 groups, based on how they treat their parameters:

Simple tags that do not take any parameters (e.g. @nil or @name). Pasdoc will show a warning if you try to pass parameters to such tags.
Tags that take their parameters and expand tags inside them too, recursively. This means that inside these parameters @-tags are expanded, whitespaces do not matter, an empty line means "start new paragraph" etc. (see WritingDocumentation). This also means that inside the parameters you must write @@ to get one @ in the output.
Example of using such recursive tag @raises:
```
   1 { @raises(EMyException
   2     when global variable @link(FailWithException) 
   3     is set to true.) }
   4 procedure MyProcedure(A: Integer);
```
Tags that take some parameters but do not expand them. These are very exceptional tags, serving a special purpose and their parameters have a special meaning. Tags belonging to this group are:
- @html tag: parameter of it must be valid HTML markup, and will be copied verbatim to the HTML output
- @latex tag: parameter is valid LaTeX markup
- @link tag: parameter is an existing Pascal item identifier
- @longcode tag: parameter of it is interpreted as a Pascal source code.
When using these tags you should note that inside their parameters @-tags are not expanded, whitespace is not interpreted in any special way (e.g. empty lines are not converted to paragraphs) etc. This also means that the @ character is not special, and you do not have to (in fact, you cannot) double it if you want a single @ in the output.

You can also specify tag parameters without enclosing them in parenthesis. So you can write

   1   { @param S is the text to print 
   2     @raises EMyException sometimes }
   3   procedure Print(const S: string);

and it is equivalent to

   1   { @param(S is the text to print) 
   2     @raises(EMyException sometimes) }
   3   procedure Print(const S: string);

Parsing logic is simple: If a tag requires some parameters but you do not put an opening parenthesis '(' char right after it, then the tag's parameters are supposed to span to the end of line (or to the end of comment). Note that this rule does not "break" the behavior of parameter-less tags like @name tag. Also it does not break comments that enclose tag parameters in parenthesis.

For more comments and examples of use you can take a look at test unit for this feature and pasdoc's output for this test unit.

Advantages of not enclosing tag parameters in parenthesis are

sometimes this tends to look better in unit source
compatibility with JavaDoc and others

You can use tags inside the comments to have PasDoc automatically add some information or have it treat some text in a special manner. A tag is always prefixed with the "@" character. Some tags require an argument which must be enclosed in braces (see also TagsParametersWithoutParenthesis), others do not, see TagsParameters.

Alphabetical list of supported tags:

@@: Insert the @ character literally
@abstract: Specify a short abstract of the description
@anchor: Set up an invisible anchor inside introduction/conclusion
@author: Specify an author's name (and email address etc.)
@bold: Format text using bold font
@br: Force line break
@cell: Create a cell in a table
@classname: Insert the class name
@code: Format argument as code example (see also LongcodeTag)
@created: Specify creation date of this item
@cvs: Obtain last modification time or author name from cvs $Date and $Author keywords
@definitionList: Create definition list
@deprecated: Mark this item as deprecated
@exclude: Exclude this item from documentation
@false: Insert the specially formatted text "false"
@html: Insert the direct HTML code into HTML output
@image: Include image file
@include: Include description from file
@inherited: Insert the name of the ancestor class or member
@inheritedClass: Insert the name of the ancestor class
@italic: Format text using italic font
@item: Make list item
@itemLabel: Define a label for next item within definition list
@itemSetNumber: Change the number of next item inside ordered list
@itemSpacing: Control the vertical spacing between items of a list
@lastmod: Specify last modification date of this item
@latex: Insert direct LaTeX code into LaTeX output
@link: Insert a link to another item
@longcode: Format argument as multiline Pascal code example (see also CodeTag)
@member: Specify description for a member (field, method, property) of a structure in description of this structure
@name: Insert the name of this item
@nil: Insert the specially formatted text "nil" here
@noAutoLink: Inside parameter of this tag auto-linking is never used
@noAutoLinkHere: Never auto-link to this item
@orderedList: Create ordered list
@param: Describe the parameter of this method (or procedure/function)
@preformatted: Insert text using fixed-width font and preserving whitespace
@raises: Describe the exception which may be raised by this method
@return, @returns: Describe function's return value
@row: Create a row in a table
@rowHead: Create a heading row in a table
@section: Start new section inside introduction/conclusion
@seealso: Create "See also" section for given item
@shorttitle: Short title of introduction/conclusion
@table: Create a table
@tableOfContents: Insert table of contents into introduction/conclusion
@title: Title of introduction/conclusion
@true: Insert the specially formatted text "true"
@unorderedList: Create unordered list
@value: Description for enumerated value in description of it's enumerated type

Some other special @-constructs:

@-: Insert short dash. Usually you can simply write "-", no need to precede it with "@", but in some special cases it's needed if you want to avoid creating en-dash or em-dash in the output. See WritingDocumentation for notes about en-dashes and em-dashes.
@(: Insert the opening parenthesis character. Usually you can simply write "(", no need to precede it with "@", but in some special cases it's needed — see TagsParametersMatching.
@): Insert the closing parenthesis character. Usually you can simply write ")", no need to precede it with "@", but in some special cases it's needed — see TagsParametersMatching.

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.

Example:

   1 type
   2   { @abstract(This class does some very useful thing.)
   3 
   4     With the help of this class you can ... (more text that
   5     describes how very very useful is this class follows). }
   6   TMyClass = class
   7   ...

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.

Note that can avoid writing explicit @abstract tag if you use --auto-abstract command-line option.

Use @author tag to specify author of this item. Use multiple @author tags if given item (e.g. unit) has many authors. Example:

@author(Johannes Berg <email@address.here>)
@author(John Doe (www.somewhere.on.the.net))
@author(Jane Doe (http://jane.doe.org))

Email or WWW addresses are automatically highlighted in the output and are clickable in HTML output. WWW addresses must either start with "http://" or "www." to be recognised.

For now @author tags will only result in documentation output for classes, interfaces, objects and units.

Tag @br forces a line break. E.g. <br> in HtmlOutput or \\ in LatexOutput.

Example:

   1 { 1st paragraph. @br Second line of 1st paragraph.
   2 
   3   2nd paragraph. Blah blah blah.
   4 
   5   3rd paragraph. @br
   6   Second line of 3rd paragraph. }
   7 procedure TestLineBreak;

See pasdoc output for this example.

Note that it's not adviced to use this tag too often, since it makes documentation ugly. In HTML, browser window should determine line width, in LaTeX, page width should determine line width, and so on. If you want to start new paragraph you should just insert an empty line (see WritingDocumentation) in description. It's possible that in some future output formats @br tag will be ignored (or equivalent to starting new paragraph) if line break will not be possible to express in this output format.

PasDoc uses the tag @code to mark example code which is preformatted and should not be changed in the output.

Example:

   1 { Declare your variables like 
   2   @code(var SomeVariable: SomeType;) }

PasDoc uses the tags @created and @lastmod to mark the creation and last modified dates of an item. They are written to a special section of the documentation.

Example:

   1 { @created(2003-05-30) 
   2   @lastmod(2003-07-01) }
   3 unit SomeUnit;

PasDoc understands text generated by CVS or SVN for $Author$ and $Date$ keywords if they are inside the parameters of a @cvs tag. $Author: ...$ text will be used as if it was specified in @author tag and $Date: ...$ text will be used as if it was specified in @lastmod tag.

Example:

   1 { @cvs($Date: 2003/05/20 20:45:05 $)
   2   @cvs($Author: Thomas Mueller <some@email.here> $) }

For PasDoc this is equivalent to

   1 { @lastmod(2003/05/20 20:45:05)
   2   @author(Thomas Mueller <some@email.here>) }

This page describes two closely related pasdoc features:

Contents

@deprecated tag
Hint directives

@deprecated tag

This tag marks given item as a deprecated. Example:

   1 { @deprecated
   2   This procedure is only for backward-compatibility,
   3   it may be removed in future versions of this unit.
   4   You should use @link(ConvertString) in new code. }
   5 procedure OldConvertString(var MyString: ShortString);

In generated documentation for OldConvertString pasdoc will try to clearly mark that procedure OldConvertString is deprecated. E.g. in HTML output at the beginning of description of OldConvertString pasdoc will write (using red font, configurable via CSS) "Warning: this symbol is deprecated."

For more examples see test unit tests/ok_deprecated_tag.pas and html output for this test unit.

Hint directives

Closely related to @deprecated tag are also Delphi "hint directives" : deprecated, platform, library. pasdoc correctly parses and understands them.

Example (equivalent to example above but this time using deprecated hint directive):

   1 { This procedure is only for backward-compatibility,
   2   it may be removed in future versions of this unit.
   3   You should use @link(ConvertString) in new code. }
   4 procedure OldConvertString(var MyString: ShortString); deprecated;

Using deprecated hint directive has the same meaning (for pasdoc) as using @deprecated tag in symbol's description (i.e. in both cases pasdoc will print this red warning "Warning: this symbol is deprecated."). But @deprecated tag is still useful, bacause

FPC does not parse Delphi hint directives. So FPC users (like me must use pasdoc's @deprecated tag instead of deprecated hint directive.
Moreover, Delphi doesn't allow hint directives for properties and non-structural types (although Kylix 3 help says that hint directives for any types are allowed). But pasdoc's @deprecated tag may be freely specified for any item in your unit, including properties and any types.

pasdoc generates appropriate "red warnings" for all hint directives in the final documentation. See test unit tests/ok_hint_directives.pas and html output for this unit.

PasDoc uses the tag @exclude to mark items that should not be in the documentation. This can be any type of item, e.g. a complete class, a method, a field etc.

When @exclude tag is placed at the class/record/interface or unit comment, then the whole item (whole class, whole unit etc.) with all it's items will be excluded.

Example:

   1 { @exclude }
   2 type
   3   TSomeHiddenClass = class
   4     ...
   5   end;
   6 
   7 type
   8   TSomePartlyHiddenClass = class
   9   public
  10     { @exclude }
  11     procedure SomeHiddenMethod;
  12   end;

Parameters of the @html tag are passed verbatim to the HTML output format.

Contents

Simple example
Notes
Example how to include graphics in HTML output

Simple example

var
  { This variable can have one of the following values:
    @html(
    <ul>
      <li>SOME_CONSTANT</li>
      <li>SOME_OTHER_CONSTANT</li>
    </ul>) }
  MyVariable: Integer;

Which will result in the following HTML output:

This variable can have one of the following values:

SOME_CONSTANT
SOME_OTHER_CONSTANT

Notes

This tag does not recursively expand its parameter (see TagsParameters), so @-tags are *not* expanded inside the parameters of this tag, paragraphs are *not* inserted, and you can simply write the @ char to get it in the output (no need to double it, like @@). Special html characters (like < or >) are *not* escaped for HTML output. You have to write < to get the < character in HTML output. To rephrase it: The text inside the parameters of @html is copied absolutely verbatim to the output.
When pasdoc generates documentation in a format, that can not use HTML markup, the @html() tag is ignored.
See also the @latex tag

Example how to include graphics in HTML output

The @html tag can be used to include graphics with the html output. For example, the following puts a figure in the top row of an (invisible) table with two rows and one column. The second row is used for a caption for the figure.

@html(
<table
style="margin-left: auto; margin-right: auto; width: 100%; text-align: left;"
border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: center;"><img src="algorithm1.png" alt="Polygon, point, and line illustrating algorithm."><br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: center;"><em>Figure 2.1, Polygon, point, and line illustrating algorithm.</em><br>
      </td>
    </tr>
  </tbody>
</table>
)

Tag @name inserts the name of current item.

The following three tags may be used only within a class, i.e. when current item is either a class or a member of some class. (Class means a real class or an interface, a record etc.)