From WxWiki

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.

Contents 1 How can I help? 2 Reviewing the Converted Interface Headers 2.1 Task List 2.2 Interface Checking Utility 3 Screenshots 3.1 Automatic Screenshot Utility

[edit] How can I help?

You can help in two ways this modernization process:

1. Reviewing the converted interface headers.
2. Helping write the automatic screenshot utility.

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

[edit] Reviewing the Converted Interface Headers

An example of what needs to be done can be seen in this diff relative to a doxygen header already processed.

Basically it means:

1. Breaking long paragraphs by adding empty lines to improve the readability.
2. Joining lines of the same paragraph so they end near column 80. This makes the documentation blocks more compact.
3. Fix the link anchor names (see docs/tech/tn0003.txt Adding wxWidgets class documentation for the naming conventions).
4. Fixing lists of items. They are not, in fact, correctly converted by the conversion script.
5. Ensure that no contents were lost during the automatic conversion (typically docs for enumerations or docs with C++ examples are messed up).
6. Add the classes to their appropriate categories by fixing the @category{FIXME} tags. A full list of categories can be found in docs/doxygen/groups/class*.h. (These files don't need to be edited.) All classes should be added to their original category, but if any others apply, you should add them to the class as well. (@category supports multiple comma-separated arguments.)
7. If you think that in some place the wx interface is incoherent (wrong parameter type: e.g. 'int' instead of 'unsigned int', non-cost function which should be const, etc.), please put a @todo comment there; the wx devs will look at it asap and will evaluate a change in the wx interface API.

Once you've finished the previous steps, launch Doxygen (using either wxWidgets/docs/doxygen/regen.sh or wxWidgets/docs/doxygen/regen.bat) and then:

1. Fix the Doxygen warnings relative to that header.
2. Check the generated HTML to verify that the resulting documentation contain the same infomation as the current latex docs.

Please read Adding wxWidgets class documentation before helping with the revision process.

[edit] Task List

If you have free time and the wx-knowledge to help with the revision of the interface headers, please assign yourself to one of these slots:

Headers to review	Person assigned to this slot	Content reviewed?	Interface-matching checked?
interface headers whose filename's first character is in range [a-b]	Francesco Montorsi	Yes	Yes
interface headers whose filename's first character is in range [c-d]	Bryan Petty	Yes	No
evtloop.h	Vadim Zeitlin	No	No
other interface headers whose filename's first character is in range [e]	Francesco Montorsi	Yes	No
other interface headers whose filename's first character is in range [f]	Francesco Montorsi	Yes	No
interface headers whose filename's first character is in range [g-h]	Bryan Petty	No	No
log.h	Vadim Zeitlin	Yes	No
other interface headers whose filename's first character is in range [i-l]	Arne Steinarson	No	No
msgdlg.h and mdi.h	Vadim Zeitlin	Yes	No
mediactrl.h, mdi.h	Utensil Candel	Yes	No
other interface headers whose filename's first character is in range [m-n]	UNASSIGNED	No	No
interface headers whose filename's first character is in range [o-p]	Utensil Candel	Yes	No
interface headers [q-r] except richtextctrl related header	Utensil Candel	Yes	No
richtextctrl related headers	Francesco Montorsi	Yes	No
socket.h	Utensil Candel	Yes	No
other interface headers whose filename's first character is in range [sa-ss]	Francesco Montorsi	Yes	No
interface headers whose filename's first character is in range [st-sy]	Francesco Montorsi	Yes	No
strconv.h, textctrl.h	Vadim Zeitlin	Yes	No
other interface headers whose filename's first character is in range [ta-ti]	Francesco Montorsi	Yes	No
interface headers whose filename's first character is in range [to-tx]	Azriel Fasten	Yes	No
interface headers whose filename's first character is in range [u-v]	Bryan Petty	Yes	No
interface headers whose filename's first character is in range [w-z]	Francesco Montorsi	Yes	Yes

Once you have completed your "slot" of headers and if you have no SVN write access, please make a diff (svn diff -u interface/myrevisedheader.h >revision.patch) and send it to the wx-dev mailing list or submit a ticket on wxTrac(http://trac.wxwidgets.org/).

IMPORTANT The Interface-matching column lists those files which were revised not only for doxygen-docs creation but also through the ifacecheck utility. For more info about it, please see: Ifacecheck utility

[edit] 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.

[edit] Screenshots

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)

[edit] Automatic Screenshot Utility

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.