3.1 fpdoc

Using FPDoc is quite simple. It takes some command-line options, and based on these options, creates documentation. The command-line options can be given as long or short options, as is common for most GNU programs.

In principle, only 2 command-line options are needed:

package: This species the name of the package for which documentation must be created. Exactly one package option can be specied.
input: The name of a unit le for which documentation should be generated. This can be a simple lename, but can also contain some syntax options as they could be given to the Free Pascal scanner. More than one input option can be given, and documentation will be generated for all specied input les.

Some examples:

fpdoc --package=fcl --input=crt.pp

This will scan the crt.pp le and generate documentation for it in a directory called fcl.

fpdoc --package=fcl --input='-I../inc -S2 -DDebug classes.pp'

This will scan the le classes.pp, with the DEBUG symbol dened, the scanner will look for include les in the ../inc directory, and OBJFPC-mode syntax will be accepted.

(for more information about these options, see the Free Pascal compiler user's guide)

With the above commands, a set of documentation les will be generated in HTML format (this is the standard). There will be no description of any of the identiers found in the unit's interface section, but all identiers declarations will be present in the documentation.

The actual documentation (i.e. the description of each of the identiers) resides in a description le, which can be specied with the descr option:

fpdoc --package=fcl --descr=crt.xml --input=crt.pp

This will scan the crt.pp le and generate documentation for it, using the descriptions found in the lecrt.xml le. The documentation will be written in a directory called fcl.

fpdoc --package=fcl --descr=classes.xml \
--input='-I../inc -S2 -DDebug classes.pp'

All options should be given on one line. This will scan the le classes.pp, with the DEBUG symbol dened, the scanner will look for include les in the ../inc directory, and OBJFPC-mode syntax will be accepted.

More than one input le or description le can be given:

fpdoc --package=fcl --descr=classes.xml --descr=process.xml \
--input='-I../inc -S2 -DDebug classes.pp' \
--input='-I../inc -S2 -DDebug process.pp'

Here, documentation will be generated for 2 units: classes and process

The format of the description le is discussed in the next chapter.

Other formats can be generated, such as latex:

fpdoc --format=latex --package=fcl \
      --descr=classes.xml --descr=process.xml\
      --input='-I../inc -S2 -DDebug classes.pp' \
      --input='-I../inc -S2 -DDebug process.pp'

This will generate a LaTeX le called fcl.tex, which contains the documentation of the units classes and process. The latex le contains no document preamble, it starts with a chapter command. It is meant to be included (using the LaTeX include command) in a latex document with a preamble.

The output of FPDoc can be further customised by several command-line options, which will be explained in the next section.

[next] [front] [up]