Gendoc tutorial

Introduction

Gendoc is a reverse engineering tool that can be used for generating HTML content from the source code of a Visual Studio C++ project. It may also be used for generating reference documentation without touching the source code files.

Gendoc reads a gendoc.xml file given to it as input argument, or a gendoc.xml residing in the current directory when no file argument is given. The gendoc.xml contains a path to a Visual Studio C++ project (.vcxproj) file. Gendoc parses the C++ sources in the project, generates binary AST file (project.ast) from the sources, and creates an XML symbol table from the AST of the current project and ASTs of any imported projects. Finally it generates hyperlinked HTML source code files and interface documents with class inheritance diagrams from the symbol table XML and ASTs.

gendoc.xml

A gendoc.xml project file may refer to a single Visual Studio C++ project, it may additionally import another gendoc project, or it may contain a list of gendoc child projects.

Single standalone project

        <?xml version="1.0" encoding="utf-8"?>
        <gendoc>
          <project name="identifier for the project"> (mandatory)
            <vcxproject file="path to a Visual Studio project"/> (mandatory)
            <documentation file="path to an XML file containing documentation"/> (optional)
            <include path="C++ INCLUDE path for parsing sources"/> (optional, directory paths separated by semicolons)
          </project>
          <filter> (optional)
            <file exclude="file pattern of source files to exclude"/> (wild cards * and ? are OK)
            ...
            <file include="file pattern of source files to include"/> (wild cards * and ? are OK)
            ...
          </filter>
        </gendoc>
    

Importing another project

        <?xml version="1.0" encoding="utf-8"?>
        <gendoc>
            ...
            <imports>
              <import project="path to a directory that contains a gendoc.xml file"/>
              ...
            </imports>
            ...
          </project>
        </gendoc>
    

Container project

        <?xml version="1.0" encoding="utf-8"?>
        <gendoc>
          <project name="identifier for the project"> (mandatory)
          <child project="path to a directory that contains a gendoc child project"/>
          ...
        </gendoc>
    

Launching gendoc

When the current directory contains a gendoc.xml to be processed, the gendoc tool can be launched without any parameters or with the --verbose or -v option for verbose output:

        C:\>gendoc -v
    

If the -v option is not used, the tool operates silently if no error is encountered.

The --single-process or -s option runs everything in a single process. Useful for debugging, if and when something goes wrong. If the -s option is not used, gendoc launches child processes of itself to process child projects.

The --clean or -l option clears generated content.

The --rebuild or -r option rebuilds everything. Without it the tool performs incremental operation and generates content only for modified files. The tool is not perfect, though. You may have to use the -r option to generate up-to-date content to be absolutely sure.

The tool can alternatively be launched with an explicit path to a gendoc.xml to process:

        gendoc -v path/to/gendoc.xml
    

This is equivalent to changing to the directory that contains the gendoc.xml, and then launching gendoc without the file argument.

Documentation XML file

(optional)

The generated HTML may be completed by specifying a path to an XML documentation file in a gendoc.xml file. The documentation XML file should consist of a sequence of doc elements inside a docs root element. Each doc element must have an id attribute whose value is an identfier of a module, class or function to document. The doc element can contain a description element and a body element. Intent is that the description element should contain a short description of the module, class or function, and the body element should contain full details. The body element can contain any XHTML elements such as hyperlinks and tables.

The contents of the documentation XML file is as follows:

        <?xml version="1.0" encoding="utf-8"?>
        <docs>
            <doc id="ID of the module, class or function to document">
                <description>Description of the module class or function</description>
                <body>
                    XHTML content
                </body>
            </doc>
            ...
        </docs>
    

Gendoc inserts the descriptions and bodies in the documentation XML file as documentation of an element with a corresponding ID in the generated HTML document.

Obtaining the ID of a module, class or function

For example: If the URL is file:///D:/work/soulng-project/doc/reference/soulng/util/html/content/class_CodeFormatter_C58CAFDB50587A7AC80B6435A31CAA3A81DB6CC9.html, the ID of it is class_CodeFormatter_C58CAFDB50587A7AC80B6435A31CAA3A81DB6CC9. That is: the ID is the URL without a container part and without the .html suffix.