
README for XDOC.EXE
-------------------

xdoc README
(W) Ulrich Mller, Feb 7, 2000
Last updated May 9, 2001


0. CONTENTS OF THIS FILE
========================

    1. LICENSE, COPYRIGHT, DISCLAIMER
    2. INTRODUCTION
    3. DOCUMENTATION STYLE
    4. CHANGE LOGS
    5. C++ SUPPORT
    6. LIMITATIONS


1. LICENSE, COPYRIGHT, DISCLAIMER
=================================

    Copyright (C) 1999-2001 Ulrich Mller.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as contained in
    the file COPYING in this distribution.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


2. INTRODUCTION
===============

    XDOC.EXE is yet another tool to automatically generate
    documentation directly from C/C++ sources. I didn't find
    any such tool that would fit my needs, especially for WPS
    programming, so I started writing my own.

    If you're not familiar with such tools: This parses C/C++
    source files directly and creates lots of HTML files
    according to the comments in the source files.

    The advantage of this is that you do not have to maintain
    documentation separate from the code, which will frequently
    become outdated. Instead, write your documentation into
    comments in the source directly, and xdoc will be able to
    extract that.

    In order for this to work, XDOC.EXE expects a certain syntax
    in the comments. This is necessary because we don't really
    want _all_ the comments to come out in the HTML output.

    Type "xdoc" at the command line to get a usage description.

    Present features:

    --  Automatic parsing of parameter comments in functions.

    --  Fully automatic cross references. For everything that
        is commented in xdoc style, xdoc will automatically
        convert every occurence in other comments into HTML
        links.

    --  C++ support. We now have class hierarchies and member
        lists.

    --  SOM/WPS support. Even though xdoc doesn't parse IDL
        files directly, it can imitate classes through special
        tags.

    --  Full change logs per definition and globally.

    --  Creation of a plain-text CHANGELOG file.


3. DOCUMENTATION STYLE
======================

    The basic idea is that the special key "@@" in a C-style comment
    will make XDOC.EXE consider this comment to be for HTML output.
    Here's the basic syntax:

        /*
         *@@ Create:
         *      create something.
         */

        PVOID Create(PVOID pvCreateFrom,    // in: create from
                     ULONG ulFlags)         // in: control flags
        {
            ... // code, ignored by xdoc
        }

    XDOC.EXE will go thru the source file and evaluate all comments
    which have the /* ... */ style. For each of these comments,
    it checks for whether the "@@" key is contained in that comment.

    If so, it is considered to document something, and XDOC.EXE will
    go for the code which comes _after_ the comment.

    a)  If the following code is a function header, XDOC.EXE will parse
        the return value, function name, and parameter list.

        For the parameter list, after each parameter, you may add another
        comment in "//" style, which documents that parameter, as
        shown above.

    b)  If the following code is a structure or class definition, xdoc
        will create an internal entry for that class and later add
        members to it. The whole struct/class definition will also be
        written as HTML output.

        xdoc does recognize the typical C "typedef struct _s { } s, *ps"
        syntax.

    c)  For member functions ("Class::Function"), xdoc will automatically
        add that function to the respective class member function index.

    d)  If the following code starts with "case" or "#define", xdoc
        recognizes the first word after "case" or "#define" as a
        definition. This allows you to document PM messages etc. in
        switch/case statements or in the headers where the messages
        are defined, at your choice.

        Example:

        /*
         *@@ WM_MYMESSAGE:
         *      blahblah.
         */

        case WM_MYMESSAGE:
                ... // code, ignored by xdoc

    Note: xdoc does not really fully parse C code. It searches for /* */
    comments first which have the "@@" tag in them. Only if such a
    tag is found, some limited parsing is performed on the code which
    follows to create a definition (as described above).

    For each such definition, one HTML file will be created. For the
    above example, this would look like the following:

        File: <filename>

        PVOID Create(PVOID pvCreateFrom,
                     ULONG ulFlags)

        Parameters:

        PVOID pvCreateFrom
            in: create from
        ULONG ulFlags
            in: control flags

        Returns: PVOID

        Description: create something.

    XDOC.EXE is smart enough to automatically produce HTML links
    if any comment contains a source item which is documented
    elsewhere. That is, if the above comment would contain a
    mention of the function "Destroy", and "Destroy" has been
    documented somewhere, XDOC.EXE would make the mention of
    "Destroy" a link to the HTML file which documents "Destroy".

    For large code bases, this link resolution can take a bit
    of time. Link resolution can be disabled on the xdoc command
    line.

    XDOC.EXE also automatically creates file indices, table of
    contents, and such things.

    This is all for now. For more examples, refer to the
    XWorkplace or WarpIN sources, which contain tons of
    documentation in this style.


4. CHANGE LOGS
==============

    When changing code, mark the code as changed in the
    comment by using something like the following:

    @@changed V0.9.2 (2000-03-10) [umoeller]: fixed memory leak
        |        |        |          |          |
        |        |        |          |          +-- description
        |        |        |          +- author tag (same as CVS login)
        |        |        +-- ISO date (year, month, day)
        |        +-- XWorkplace/WarpIN version number
        +-- fixed xdoc tag

    xdoc can create change logs per declaration and also a global
    change log if these things are set properly. Try "createdoc.cmd"
    in the WarpIN and XWorkplace main source directories, respectively.

    When adding a new function, use the same, just use "@@added"
    instead of "@@changed".


5. C++ SUPPORT
==============

    xdoc now (V0.9.18=) has full C++ support. Well, "full" means
    that it can handle all constructs that are presently used in
    WarpIN and produce acceptable output.

    Most notably, it can

    --  correlate functions to classes

    --  display class hierarchies

    --  resolve overridden methods

    --  handle overloaded functions by comparing the argument
        lists.

    If a comment introduces a "struct" or a "class", xdoc will
    parse the entire definition (with "{" and "}") for additional
    comments. This will allow you to things like this:

        class Base
        {
            public:

                /*
                 *@@ Dump:
                 *
                 */

                Dump(FILE *file)
                {
                }
        }

        /*
         *@@ Derived:
         *      derived class.
         */

        class Derived : public Base
        {
            public:

                /*
                 *@@ Derived:
                 *
                 */

                Derived() {};

                /*
                 *@@ ~Derived:
                 *
                 */

                ~Derived() {};

                /*
                 *@@ Dump:
                 *      override of Base::Dump(FILE *).
                 */

                APIRET Dump(FILE *file);

                /*
                 *@@ Dump:
                 *      overloaded Dump, newly introduced
                 *      in class Derived.
                 */

                APIRET Dump(HFILE hFile);
        };

        /*
         *@@ Dump:
         *
         */

        APIRET Derived::Dump(FILE *file)     // in: output file from fopen()
        {
            ...
        }

    xdoc will recognize both the functions in the class definition as
    well as the external Derived::Dump definition as class members and
    list them with the class entry in the class hierachy. It will
    even realize that you have overridden Base::Dump(FILE *) in Derived.

    xdoc does not differentiate between the "class" and "struct"
    keywords. If any member functions are found, xdoc's class
    mechanism is enabled. Otherwise the full struct definition
    is dumped.

    Starting with X0.9.18, xdoc also handles template definitions
    finally and fixes a few other C++ quirks.


6. LIMITATIONS
==============

    xdoc is now capable of generating pretty useable documentation
    for XWorkplace and WarpIN (including the shared "xwphelpers"),
    so it can be considered quite useful already.

    However:

    --  Even though xdoc is fairly stable now -- should it
        crash on your sources, use the "-v4" option for maximum
        verbosity and check which code fragment causes the crash.


