a first attempt at documenting the WTL classes.
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.
- View online [discontinued]
- Download zip file (1.3Mb zipped, 8.96Mb unzipped)
- Download tar/gzip file (1Mb zipped, 8.96Mb unzipped)
- Download build files zip or tar/gzip (requires WTL7 and Doxygen installed).
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 "
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:
- There are a variety of "@..." tags that can be used, see the Doxygen documentation for a full list.
- The full declaration of the class or function needs to be used.
- HTML markup is allowed and encouraged within the documentation.
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
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.