Documentation XML pour le code Object Pascal

De Appmethod Topics
Aller à : navigation, rechercher

Remonter à Sortie XML du compilateur


Les trois compilateurs Object Pascal (DCC32.EXE, DCC64.EXE et DCCOSX.EXE) peuvent générer de la documentation XML pour le code source compilé.

  • Pour activer cette fonctionnalité depuis la ligne de commande, exécutez DCC32.EXE et définissez l'option --doc (voir l'exemple ci-dessous).
  • Pour activer cette fonctionnalité depuis l'EDI, allez sur Projet > Options > Compilateur Object Pascal > Compilation > Autres options et définissez l'indicateur Générer la documentation XML.

La documentation XML générée par le compilateur est créée à partir de la représentation interne du compilateur des classes, des méthodes, des variables, et ainsi de suite. Ne la confondez pas avec la documentation XML écrite manuellement (voir Commentaires de documentation XML).

Remarque : Vous pouvez générer la documentation HTML pour un projet Appmethod spécifique à Object Pascal (ou C++) : voir Génération de la documentation d'un projet.

Le format (schéma) du fichier XML est décrit dans Déclarations globales de sortie du compilateur XML.

Exemple

Le fichier "C:\file.pas" contient la définition d'une :

  • Enumération : TFocus
  • Classe : TVideoCamera

Invocation en ligne de commande de DCC32.EXE :

dcc32 --doc "C:\file.pas"

Enumération

Définition de TFocus :

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

Documentation XML générée :

 <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>

Notez que les commentaires de la documentation XML sont inclus dans la documentation XML générée par le compilateur (voir les éléments devnotes).

Classe

Définition de TVideoCamera :

  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;

Documentation XML générée (certains membres hérités de TObject ont été retirés pour plus de clarté) :

  <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>

Voir aussi