1.3 About Txt2FPDoc

     

     
Figure: Process of creating documentation with Txt2FPDoc  

Txt2FPDoc is a documentation tool for Free Pascal and Lazarus code. It's a command line utility that converts a documentation file written in human readable language to an XML file suitable for FPDoc.

Txt2FPDoc tries to make the documentation file easy to read (almost as readable as plain English) and easy to write (no cryptic tags, only light markups like ‘**bold**’ and ‘//italic//’).

The documentation can be stored in one or more text files or directly included in the source code.

Here is a quick example of how to document a function for Txt2FPDoc:

     Example: Documentation of Multiply for Txt2FPDoc  
      1 {** Function: Multiply -- Multiplies two integers.
      2
      3     Parameters:
      4       - A -- first integer
      5       - B -- second integer
      6
      7     Result:
      8       The two integers multiplied together. }
      9 function Multiply(A, B: Integer) : Integer;

For comparison, here's the XML code that you should write to get the same result with FPDoc:

     Example: Documentation of Multiply for FPDoc  
      1  <element name="Multiply">
      2    <short>Multiplies two integers.</short>
      3  </element>
      4
      5  <element name="Multiply.Result">
      6    <short>The two integers multiplied together.</short>
      7  </element>
      8
      9  <element name="Multiply.B">
     10    <short>second integer</short>
     11  </element>
     12
     13  <element name="Multiply.A">
     14    <short>first integer</short>
     15  </element>

Last, the following screenshot shows how it could be rendered in a web browser once converted to HTML by FPDoc.

     

     
Image: Documentation of Multiply in a web brower