XML Documentation for C++ Code

Go Up to Command Line Utilities Index

Introduction

The C++ compiler can generate an XML file with the declarations from a C++ source file and the included headers. The information that is generated is similar to the information being displayed by the C++Builder Class Explorer, in the sense that both display information from the compiler's symbol table. This topic describes the -Zx option, which can be used with BCC32 to generate XML documentation.

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

BCC32 Command Options for XML Output

-Zx - Generate XML Output

The -Zx option of BCC32 prompts the compiler to generate an XML file of the symbols encountered while processing a C++ source file and its headers. For example, given the following source file (test.cpp), the command BCC32 -Zx test.cpp produces the XML file test.xml shown below:

Command syntax

bcc32 -Zx test.cpp 

test.cpp

class TBase {
  int id;
};

class TDerived : public TBase {
  char *name;
};

test.xml

---

<?xml version="1.0" encoding="utf-8"?>
<file name="test.cpp">
    <class name="TBase" visibility="public">
        <members>
            <field name="id" type="int" visibility="private" />
        </members>
    </class>
    <class name="TDerived" visibility="public">
        <ancestor name="TBase">
            <fieldref name="id" visibility="private" />
        </ancestor>
        <members>
            <field name="name" type="char *" visibility="private" />
        </members>
    </class>
</file>

The -Zx option also accepts suboptions. These can be seen when running the following help (-h) command:

Command syntax

bcc32 -h -Zx 

The resulting output is the following:

-Zx     Output global definitions to XML file.
     Sub Options:
           -Zx=<filename> Emit only types/declarations in <filename>
           -Zxf[=filename] Skip base type members 
           -Zxm[=filename] Emit macros
           -Zxp[=filename] Emit file & line position

-Zxf - Skip Ancestor Information

When processing a class for XML output by default, BCC32 will generate information about members of the base types (ancestors) of that class. The 'f' suboption instructs the compiler not to generate any information for base types. The following table illustrates how the suboption 'f' changes the generated .xml for the test.cpp file.

Command syntax

bcc32 -Zxf Test.cpp

test.xml (without 'f' suboption)

---

<?xml version="1.0" encoding="utf-8"?>
<file name="test.cpp">
    <class name="TBase" visibility="public">
        <members>
            <field name="id" type="int" visibility="private" />
        </members>
    </class>
    <class name="TDerived" visibility="public">
        <ancestor name="TBase">
            <fieldref name="id" visibility="private" />
        </ancestor>
        <members>
            <field name="name" type="char *" visibility="private" />
        </members>
    </class>
</file>

test.xml (with 'f' suboption)

---

<?xml version="1.0" encoding="utf-8"?>
<file name="test.cpp">
    <class name="TBase" visibility="public">
        <members>
            <field name="id" type="int" visibility="private" />
        </members>
    </class>
    <class name="TDerived" visibility="public">
        <members>
            <field name="name" type="char *" visibility="private" />
        </members>
    </class>
</file>

-Zxp - Generate Position Information

The 'p' suboption instructs BCC32 to include attributes describing the file and line of each declaration. The following table illustrates test.xml with the 'p' suboption enabled.

Command syntax

bcc32 -Zxp Test.cpp

test.xml (with 'p' suboption)

---

<?xml version="1.0" encoding="utf-8"?>
<file name="test.cpp">
    <class name="TBase" visibility="public" file="test.cpp" line="1">
        <members>
            <field name="id" type="int" visibility="private" file="test.cpp" line="2" />
        </members>
    </class>
    <class name="TDerived" visibility="public" file="test.cpp" line="5">
        <ancestor name="TBase">
            <fieldref name="id" visibility="private" />
        </ancestor>
        <members>
            <field name="name" type="char *" visibility="private" file="test.cpp" line="6" />
        </members>
    </class>
</file>

See Also

• BCC32.EXE, the C++ 32-bit Command-Line Compiler
• XML Documentation for Delphi Code
• XML Documentation Comments