Lit Window Productions

Products
Shop
Knowhow
wxHowto
Intellisense
wxDoxygen
wxSocket
HowTo
Library
About

RSS Feed
What’s this?

Contact
Privacy

Fast, easy dialog editing and code generation with Anthemion’s Dialog Editor for wxWidgets...

BugLister

Small, fast and easy bug tracking system by Lit Window Productions.

IMPORTANT: wxWidgets is an open source crossplatform library and in no way associated with Lit Window Productions. wxWidgets homepage is www.wxWidgets.org

Quick Summary

  • modify tex2rtf to produce .cpp files with doxygen comments.
  • use tex2rtf to convert the wxWidgets .tex files into .cpp files.
  • use doxygen to convert the generated .cpp files and the wxWidgets source hierarchy.

Click here to view the documentation for wxBitmapButton.

Creating wxWidgets documentation with doxygen.

It has been proposed a few times to use Doxygen to create the documentation for wxWidgets. wxWidgets currently uses LaTex files and the tool tex2rtf, written (mostly) by Julian Smart.

Doxygen or Latex / tex2rtf?

There are many arguments for and against using Doxygen or sticking with tex2rtf. Some information can be found on the wxWidgets wiki pages: wiki.wxWidgets.org, others in the mailing list archives.

From these sources I get the impression that the biggest problem the wxWidgets community has with using doxygen is that we would have to ‘backport’ the existing documentation in latex style and move it into the wxWidgets header files. This would be a prohibitive amount of work to do manually. There have been some proposals and attempts to automate this but none have been successful enough to move on.

Howto: have both, Doxygen and Latex / tex2rtf.

My idea is pretty simple.

  • Extend tex2rtf so that it produces .cpp files with doxygen comments from .tex
  • Run tex2rtf and generate .cpp files from the entire wxWidgets documentation.
  • Run doxygen with the generated .cpp files and the wxWidgets source hierarchy.

This is what I did and although the work is not finished, the initial results look very promising.

  • Click here to view the doxygen documentation for wxBitmapButton. Note: links to other doxygen generated pages do not work, because the other pages have not been published here.

What remains to be done.

Although the result look quite nice, employing this technique requires further work that will have to be done by volunteers. And from experience we all know that “looks quite nice”  means only half way there. We can run into a lot of unexpected problems.

This is a list of what remains to be done:

  • Read and fix all of the 1000+ warnings that doxygen complains about. There are quite a few functions where the declaration and function do not match.
  • Read and compare the generated documentation with the current version. Make sure we do not drop information in the process.
  • And generally: improve the existing documentation.

This is still a lot of work, but it could be done easily, if enough people volunteer to spend a few hours.

What would be the benefits.

Much of this has been discussed over and over. See the sources above.

Personally I think, the greatest benefit would be that there is one less argument left against properly documenting the sources and we could start immediately improving the docs. There are many classes and events still undocumented. I wasn’t able to find wxPopupWindow for example and only stumbled across it, because i grep-ed for WS_POPUP.

Also many, many comments in the sourcecode are very good and can be converted to the doxygen style quite easily. Simply replacing /* with /** is enough in most cases.

And those that prefer LaTex over doxygen can still write their documentation in .tex files.

The technical details behind it.

This gets technical and is not really neccessary to understand the idea. Read on, if you like to know the details.

A few interesting things about doxygen.

What is often overlooked is that doxygen does not require you to put the comments in front of the objects you want to document. The comments need not even be in the same source file.

My idea uses the \fn doxygen command. \fn returntype function(arguments) begins a function documentation block. This is why converting the .tex files into .cpp files works.

Even better, I found out - by accident - that doxygen has a very relaxed approach when it encounters the same class declaration multiple times. It simply merges all methods. This is very good news, because it solves several problems at once. More on that further on.

Enhancing tex2rtf

I have added a new output mode ‘doxygen’. It is partly based on the HTML output, because doxygen understands many html commands. The important part is creating the doxygen comments.

For example, tex2rtf -doxygen will output ”/*! \class wxButton” when it encounters an \class{wxButton} macro in the .tex.

Creating documentation for the wxWidgets API

Problem 1: merging wxButtonBase and wxButton

    In the documentation we want to have just one class, but the implementation is split between wxSomethingBase and a derived class wxSomething.

Solution 1: defining a macro wxButtonBase=wxButton

    Doxygens ‘merge’ feature takes care of that. When it encounters the class declaration for wxButtonBase, it uses the macro and substitutes wxButtonBase with wxButton. The class is parsed as if it was the wxButton declaration. Later, when it parses the actual wxButton class, it simply merges (union) the two declarations.

Problem 2: wxButton::GetLabel is documented, but is implemented as wxControl::GetLabel.

    Sometimes a function is implemented in a base class of the hierarchy and its semantic is slightly extended in a subclass. GetLabel has a wxButton specific documentation, but there does not exist a wxButton::GetLabel function.

Solution 2: tex2rtf creates a fake class declaration containing this function.

    This is what tex2rtf will produce in the generated .cpp file.

    class wxButton
    {
    public:
       wxString GetLabel() const;
    };
    /*! \fn wxString GetLabel() const
    ...

    Doxygen will then merge this fake class declaration with the original wxButton class declaration and allow the “re”documentation of wxButton::GetLabel().

[Home] [Products] [Shop] [Knowhow] [Library] [About]

© 2004, Hajo Kirchhoff, last modified Mar 06, 2008

email

back to top

webhosting by netissimo