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.


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:

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).

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:

WritingDocumentation (last edited 2008-08-03 05:06:53 by Hans-Peter Diettrich)