[Codeworks Home]

a first attempt at documenting the WTL classes.

Overview

WTL is undocumented and unsupported. That means there is a growing need for documentation, tips and tricks. These pages are an attempt to create some documentation for the library.
One of the requirements for the documentation is that it needs to be easy to maintain, especially when further releases of WTL appear, this means that hand written docs are not the best choice. What is needed is a way of integrating the information that we can extract from the library source itself with some annotations supplied by others.
The easiest way to extract the information from the source code is to make use of Doxygen, a program that parses the source code and formats it into a variety of documentation formats. In this case I'm using HTML as the output format, but it is also possible to create Latex, RTF, man and XML format documentation using the same technique.
The next task is to add annotations, and Doxygen allows us to create and add an external documentation file that will, by the judicious use of tags, be inserted into the correct place in the output source. So all that is needed is to create the external documentation and then feed it into the Doxygen parsing process.

Bjarke Viksøe has allowed me to use many of his annotations in this documentation, for which many thanks. Take a look at his pages. Specifically, he has created a set of templates, one for each WTL class, that can be filled in with documentation details. I then have a Perl script that pulls all that into a format ready for Doxygen. See below for more details on the process.
I've also taken some documentation from Bryan Kessler's excellent WTL Quick Ref document (which seems to have disappeared from the web).

The documentation is available in a variety of ways. You can view it online, download it as a zip file to install locally or on an intranet, or download Doxygen, the configuration files and then build the documentation yourself. This project is only just started, so there is still a lot of work to be done.

External documentation format and how you can contribute.

Adding external documentation to the Doxygen process is reasonably straightforward, although there are some strict rules to be followed. Here is a brief overview of the process (but not a tutorial on Doxygen, see their excellent docs for that).
Each file, class, function etc. can have an associated comment, usually a block that starts with "/**" (Javadoc format) or "/*!" (QT style). Its important to realise that to document a function, the enclosing class and file must be documented (otherwise Doxygen will not know where to add the annotations).
For exampe (using the Javadoc style): 

/** @file AtlFrame.h
    @brief a documented file containing stuff on frames.

    AtlFrame.h contains the definitions for:
And so on...
*/
/** @class WTL::CDialogResize
    @brief class for dialog resizing

    <b>Usage Notes</b>
Some desciptive and profound annotations go here
*/
/** @fn inline void WTL::CRect::NormalizeRect()
*  @brief Make sure that left and top are greater than right and bottom
*         Swap them if not.
*/

This firstly documents the file atlframe.h, which contains the class CDialogResize and then documents the class itself. Additionally we would want to document the methods and variables within the class.
Some things to note:

So, to add some documentation to the pile, just send me your texts, preferably nicely formatted as above (altho I could do that for you if needed) and I'll do a rebuild of the docs whenever I have enough extra material to make it worthwhile. If you want further ideas on how to add text, then take a look at the extra-documentation file in the wtl7build.tgz file (see downloads above).
Given that it is a clear process, it would be nice if we could start with a set of blank templates to fill in, and Bjarke has supplied some blank templates (one for each class) to be filled in, they are available here.