XML Documentation for Object Pascal Code

From Appmethod Topics
Jump to: navigation, search

Go Up to XML Compiler Output

Object Pascal compilers can generate XML documentation for the compiled source code.

To enable this feature, select Project > Options > Object Pascal Compiler > Compiling and enable the "Generate XML Documentation" option under Other Options.

The compiler-generated XML documentation is created from the internal representation that the compiler uses for classes, methods, variables, and so on. Do not confuse the XML documentation that compilers generate with the manually written XML inline documentation.

Note: You can generate HTML documentation for a specific Object Pascal (or C++) Appmethod project. See Generating Project Documentation.

The format (schema) of the XML file is described in Compiler XML Output Global Declarations.


File C:\file.pas contains the definition of:

  • An enumeration: TFocus.
  • A class: TVideoCamera.


TFocus definition:

/// <summary>
/// For objects located closer than 10 meters, use fcNear;
/// otherwise use fcFar.
/// </summary>
TFocus = (fcNear, fcFar);

Generated XML documentation:

<const name="fcNear" type="TFocus" file="C:\file.pas" line="13">
<const name="fcFar" type="TFocus" file="C:\file.pas" line="13">
<enum name="TFocus" file="C:\file.pas" line="13">
      For objects located closer than 10 meters, use fcNear;
      otherwise use fcFar.
  <element value="0" name="fcNear" file="C:\file.pas" line="13" />
  <element value="1" name="fcFar" file="C:\file.pas" line="13" />

Note that the XML documentation comments are included in the compiler-generated XML documentation (see the devnotes elements).


TVideoCamera definition:

TVideoCamera = class
  FFocus: TFocus;
  property Focus: TFocus read FFocus write FFocus;
  procedure SetFocus(ADistance: Integer);

procedure TVideoCamera.SetFocus(ADistance: Integer);
  if ADistance < 10 { meters } then
    FFocus := fcNear
    FFocus := fcFar;

Generated XML documentation (some members inherited from TObject are removed for clarity):

<class name="TVideoCamera" file="C:\file.pas" line="15">
  <ancestor name="TObject" namespace="System">
    <methodref name="Create" visibility="public" procflags="constructor">
    <methodref name="Free" visibility="public">
    <field name="FFocus" type="TFocus" visibility="private" size="1" offset="4" file="C:\file.pas" line="17" />
    <property name="Focus" visibility="public" read="FFocus" write="FFocus" type="TFocus" file="C:\file.pas" line="19" />
    <procedure name="SetFocus" visibility="public" file="C:\file.pas" line="20">
        <parameter name="ADistance" type="Integer" />

See Also