CmDoc Documentation Generator

cmdoc is a tool for generating HTML documentation with hyperlinked source code for a Cmajor solution. The source code can be linked with the system library documentation.

Table of contents

1 Tutorial

In this tutorial we go through creating a simple example program and some documentation for it. The documentation can be created with any text editor that can save the text with UTF-8 encoding. In this tutorial we use Windows notepad.

• Create a new Cmajor console application project under the C:\cmajor\projects folder. We create also a new solution for it, because cmdoc operates with solutions.

  

• Add a new source file to it:

  

• Create some source code, compile and save the project:

  

• Create a new folder named CmDocExample for the project documentation under the C:\cmajor\doc\projects folder, open a command prompt to that folder and create an XML file for the project with name CmDocExample.cmdoc.xml:

  

• Create a cmdoc element to the XML file, and under it a solution element with a filePath attribute that points to the CmDocExample.cms solution file. Create also a target element with a dir attribute that points to the current directory. The documentation will be generated to the target directory. Finally create a libraries/library element with a dir attribute that points to the C:\cmajor\doc\system directory. This links the generated documentation with the system library documentation.

  So the contents of the XML file is as follows:

  

• Run command cmdoc --verbose CmDocExample.cmdoc.xml from the C:\cmajor\doc\projects\CmDocExample directory:

  

• The cmdoc program creates two directories: content and style, an index.html file that is the root HTML documentation file and some XML files to the target directory:

  

• The generated index.html looks now like this:

  

• Now create an XML file named docs.xml to the C:\cmajor\doc\projects\CmDocExample directory that will contain documentation for the example program:

  

• Open the index.html and click the link for the CmDocExample module, then the link for the main() function and then copy the part of the address coming after the '#' from the address line to the clipboard:

  

• Create a docs element to the docs.xml file and under it a doc element. Then create an id attribute for the doc element, and paste the id for the main function from the clipboard as the value of it. We have created three elements under the doc element: the desc element contains the description of the main function, and any possible details elements will contain detail paragraphs for it:

  

• Now edit the CmDocExample.cmdoc.xml file by adding a doc element with a filePath attribute with the value docs.xml.

  

• Run the cmdoc command again:

  

• Now view the index.html. The written documentation appears:

  

• The source code of CmDocExample/main.cm looks like this:

  

• If you click the Console link from the source code, the documentation for the Console class of the system library appears:

  

• That's the end of this tutorial.

2 Reference

The cmdoc program processes two XML files: an input XML file SOLUTION.cmdoc.xml and a documentation XML file (for example docs.xml).

2.1 Input File Format

The format of the SOLUTION.cmdoc.xml file, where SOLUTION is the solution to be documented is as follows:

        <cmdoc>
          <solution filePath="SOLUTION_FILE_PATH.cms"/>
          <doc filePath="DOCUMENTATION_FILE_PATH.xml"/>
          <target dir="TARGET_DIRECTORY_PATH"/>
          <libraries>
            <library dir="EXTERNAL_DIRECTORY_PATH"/>
            <library dir="EXTERNAL_DIRECTORY_PATH"/>
            ...
          </libraries>
        </cmdoc>
    

where

• SOLUTION_FILE_PATH is a relative path to a solution file (SOLUTION.cms),
• DOCUMENTATION_FILE_PATH is a relative path to a documentation XML file (for example docs.xml),
• TARGET_DIRECTORY_PATH is a path to the directory where the documentation will be generated (for example .), and
• EXTERNAL_DIRECTORY_PATH is a relative path to a directory that contains a documentation of another solution, for example a relative path to the C:\cmajor\doc\system directory.

The doc, libraries and library elements may be missing.

2.2 Documentation File Format

The format of the documentation file (for example docs.xml) that contains the documentation for a solution is as follows:

        <docs>
            <doc id="ID">
                <desc>
                  DESCRIPTION
                </desc>
                <details>
                  DETAILS paragraph 1
                </details>
                <details>
                  DETAILS paragraph 2
                </details>
                ...
            </doc>
            <doc id="ID">
                <desc>
                  DESCRIPTION
                </desc>
            </doc>
            ...
        </docs>
    

Each documented program entity has a single desc element that is obligatory. The desc contains the description text of an entity. The documented entity may have zero or more details elements that represent detail text paragraphs. Only a namespace, class, concept and enumeration may have details elements.

The ID is the documentation identifier of the program entity to be documented.

Each documented program entity has an URL. The URL of an entity can be found out by clicking a link of it in the documentation source code or in other generated documentation. The URL will be shown in the address line of the browser. When you got an URL of an entity, the ID of it can be derived from it as follows:

DESCRIPTION and DETAILS texts can contain a <ref>ID</ref> elements, where ID is the documentation identifier of a program entity. Each ref element will be substituted by a HTML link to the documentation of referenced entity.

DESCRIPTION and DETAILS texts can also contain other HTML elements that are preserved in the generated documentation.

A details element may have a title attribute with a value that will become a section title in the generated documentation.

2.3 Usage

Usage: cmdoc [options] { INPUT_FILE.cmdoc.xml }

Generate documentation for a solution in input file INPUT_FILE.cmdoc.xml.

Options: