Hi,
I read the Lazarus mailing list archive with the discussions about documentation and what pasdoc needs to have to be more useful. I modified pasdoc and now send some information on the update to this list because most pasdoc users seem to read it ;-) The latest version (0.6.15) is now available on the homepage at
http://pasdoc.sourceforge.net/.
1) External file switch -c
Pasdoc now supports loading of descriptions from one or more external files. You specify such a text file with the -c switch:
pasdoc src/*.pas -c descr1.txt -c descr2.txt
In theory you could put /all/ descriptions in a single file, but that wouldn't make much sense for distributed development as in the case of Lazarus. Let's say you take one description text file per unit, e.g. buttons.txt for the buttons unit. It could look like this: -- beginning of file buttons.txt
# Buttons.TButton.FDefault
This is a description of the field
FDefault of class TButton in unit Buttons.
If you feel lucky, you can leave out the unit or even class name, but chances are that there may be other items called FDefault. Specifying the whole 'path' to an item also makes it easy to merge description files.
Anyway, it is important to have one line with # at the beginning followed
by whitespace and then the item name. After that an arbitrary number of
descriptive lines like these.
That's why # characters cannot appear as the first character of a description line, I hope that's not a problem.
Those description lines are treated the same way as a comment that precedes the item in the interface section of a unit. # buttons.TButton.FModalResult
Description of FModalResult...
...
-- end of file buttons.txt
Note that there is a possible problem now in cases where you have specified descriptions in an external file /and/ the interface section of the unit. Pasdoc writes a warning to stdout in these cases and takes the description from the interface section.
This switch needs more thorough testing, so please tell me about problems here!
2) Include file switch -u DIR
This is relatively new - to tell pasdoc where to look for include files, use the -u DIR switch:
pasdoc src/*.pas -u inc -u src
will make pasdoc look in the current directory first, then in subdirectory inc,
then in subdirectory src. As soon as one include file could be opened, the search
is over (in case you have include files of the same name in two or more of the
specified directories).
3) Pasdoc homepage has changed
It has moved to http://pasdoc.sourceforge.net/, there is a mailing list as well.
4) Implementation section of units
Just to make it clear, pasdoc never touches the implementation section of a unit. As soon as it encounters the implementation keyword in a unit, it closes the file!
5) Translators wanted
Pasdoc currently knows English, French, German, Catalan and Spanish. Slovak may be added soon. If you speak another language (Dutch, Russian, ...), please translate the 45-50 string constants in gendoc.TDocGenerator.GetEnglishString and send them to me! Or drop me a mail and I'll send you these strings! I learnt from feedback that people like to use their native language for documentation.
6) Author tags
Within an author tag you don't have to escape the @ character by using @@ - simply use the following (nested parentheses are possible), example:
@author(Marco Schmidt ())
BTW, email addresses in author tags are now recognized and appear in HTML output as mailto links.
Regards,
Marco