Development: Documentation

The wxWidgets documentation is being converted from the current latex sources to a Doxygen compatible format.

For information about the decision to move to Doxygen you can look at Development: Alternative Documentation Formats as well as the endless discussions on the wx-dev mailing list that took place several times between about 2003 through 2008. After all these discussions, the wxWidgets development team has finally agreed on creating a set of wxWidgets headers to use as "interface headers", from which the documentation is extracted and published using Doxygen.

This accepted solution is not open for discussion again, the decision was thoroughly discussed and every conceivable possibility was investigated.

This page is now dedicated to the current status and remaining issues involving the migration to Doxygen.

Remaining Issues

The bulk of the work of the migration to Doxygen is now finished, but if you would like to still help with improving the documentation even more, these documentation sub-projects might be worth looking into:

• ifacecheck - The #Interface Checking Utility, providing automated validation and corrections to any inconsistencies between the real wxWidgets headers used for building and the interface headers used for documentation.
• screenshotgen - The #Screenshot Utility, providing automated screenshots of various windows and controls on each platform for inclusion to the documentation.

You will need to checkout the wxWidgets SVN trunk to help.

Interface Checking Utility

We need a tool which heuristically checks that the function prototypes of the interface headers are in synch with the prototypes in the real headers.

The wxWidgets trunk contains an implementation of such utility using GccXML and Doxygen; you can find it in the Index of /wxWidgets/trunk/utils/ifacecheck

The GccXml tool is used to parse the C++ wxWidgets "real" headers and create an XML representation of their contents; Doxygen is used to create an XML representation of the wxWidgets "interface" headers.

Then the ifacecheck utility (that's the name of the implementations which is in trunk), simply loads and compares those two XML files pointing out incoherences.

The utility already works and is indeed usable. Some improvements can be made however; interested people are welcome to discuss ideas about it on the wx-dev mailing list.

Screenshot Utility

We also need screenshots of the following classes (in alphabetic order):

wxAnimationCtrl wxBitmapButton wxBitmapComboBox wxBitmapToggleButton wxButton wxCalendarCtrl wxCheckBox wxCheckListBox wxChoice wxCollapsiblePane wxColourPickerCtrl wxComboBox wxComboCtrl wxControl wxDataViewCtrl wxDataViewTreeCtrl wxDatePickerCtrl wxDirPickerCtrl wxFilePickerCtrl wxFontPickerCtrl wxGauge wxGenericDirCtrl wxHtmlListBox wxHyperlinkCtrl wxListBox wxListCtrl wxListView wxOwnerDrawnComboBox wxRadioBox wxRadioButton wxRichTextCtrl wxScrollBar wxSimpleHtmlListBox wxSlider wxSpinButton wxSpinCtrl wxStaticBitmap wxStaticBox wxStaticText wxTextCtrl wxToggleButton wxTreeCtrl wxVListBox

under the following platforms:

1. wxGTK trunk under a recent GNOME/GTK (GTK >= 2.12) with the default Ubuntu theme "Human"
2. wxMSW trunk under Windows XP (not Vista) with the default "Windows XP" theme
3. wxMac trunk under Mac OS X (at least version 10.4 (Tiger), but 10.5 (Leopard) would be preferred)

To make this task easier it was suggested that a utility be written which can run on the three platforms. It would automatically take screenshots of each of the suggested controls, and save them in the appropriate location for the platform in use.

Updating the screenshots in the future would be as easy as building the utility, running it, and hitting a menu item. Additionally, this would ensure consistency for the screenshots on each platform with what each control shows, how big it is, what styles were used, the size of the borders, etc.

We wouldn't need to request the help of the community to take screenshots for future versions either, and if we were good about running this utility before each release, the docs would never contain an outdated screenshot of what any one control used to look like in previous versions.

If you're willing to write such (simple) application, please let us know dropping a mail to wx-dev mailing list. Thanks!

Update See Automatic screenshot creator utility for a first implementation.