Show: Object Pascal C++
Display Preferences

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.

Example

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

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

Enumeration

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

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

Class

TVideoCamera definition:

TVideoCamera = class
private
  FFocus: TFocus;
public
  property Focus: TFocus read FFocus write FFocus;
  procedure SetFocus(ADistance: Integer);
end;
 
procedure TVideoCamera.SetFocus(ADistance: Integer);
begin
  if ADistance < 10 { meters } then
    FFocus := fcNear
  else
    FFocus := fcFar;
end;

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>
    <methodref name="Free" visibility="public">
    </methodref>
  </ancestor>
  <members>
    <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">
      <parameters>
        <parameter name="ADistance" type="Integer" />
      </parameters>
    </procedure>
  </members>
</class>

See Also

Personal tools
In other languages