XML Documentation for Delphi Code

From RAD Studio
Jump to: navigation, search

Go Up to XML Compiler Output


Delphi compilers can generate XML documentation for the compiled source code.

To enable this feature, select Project > Options > Delphi Compiler > Compiling and enable the "Generate XML Documentation" option under Other Options.
To enable this feature on the command line, run the command-line compiler with the --doc option.

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 Delphi (or C++) RAD Studio 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