Using Doxygen For The WxWidgets Documentation

From WxWiki

Jump to: navigation, search

It has been proposed to use Doxygen for wxWidgets API documentation, see Development: Documentation for more details about implementation issues. Lots of them ;).

Andy Cedilnik has been working on writing a preprocessor which will strip comments out of LaTeX files and place them in the header files, which would be cool, but we haven't heard from this for a long time.

Hajo Kirchhoff has been working on extending tex2rtf to produce .cpp files, which doxygen can parse. More info can be found here. Volunteers needed to do the remaining work. If you want to volunteer, please say so in the wx-users mailing list or use the feedback form on http://www.litwindow.com.

Contents

[edit] Another Testbed

Proof that wxControl has been made a parent of wxObject and wxWindow, and proof that documentation need not be in the source or header files, can be found here:

Hint: If you just want to use Doxygen to help you find your way around wxWidget sources while this documentation issue is resolved, you can get half-decent quick and dirty source-level documentation by tossing the wxWidgets source code for a given platform (exclude all others) at Doxygen and setting ENABLE_PREPROCESSING = NO. It isn't production quality but it beats grepping.

[edit] Pros/Cons for Moving to Doxygen

[edit] Pros

  • Most developers already know Doxygen or wouldn't mind learning it (since it'd be useful for other projects, too). They could easily 'doxygenify' the comments they *should* be writing anyway, just by looking at some examples. I think now most of them don't bother to learn some strange tex-based system specific to wxWidgets.
  • When the code changes, docs are more likely to be updated with it.
    • Not really, you still have to switch to whatever file the doxygen comments are in to update them, which is only slightly more convenient than switching to a tex file. --SnakeChomp
      • Only if the comments are stored separately. One of the strengths of doxygen is that method docs can immediately precede the implementation, making them right in the developer face and hence more likely to be updated --AndyDent
  • No more unintentionally undocumented functions. Undocumented functions would show up in the docs, making clear that it exists and is part of the official API.
    • This won't work if you want to hide things intentionally as well, ie private functions and classes for internal use. It's one or the other. --SnakeChomp
      • Doxygen has settings for hiding private API. In fact, this would allow for having 2 separate sets of documenation, one for users of the library, and one for developers working on the library. --Tierra 16:43, 9 April 2006 (PDT)
  • Users (not developers) who consider contributing don't want to learn TeX.
    • Doesn't sound convincing, if someone would contribute a good piece in *any* format I'm sure someone else would step forward and convert it. --ARN
  • Searching for stuff in the doxygen-generated html might be easier than searching the header files
  • Doxygen supports overview pages and automatically generates separate todo lists, bug lists, and deprecated lists. It also tells you when and where virtual functions are overridden. Creating groups of member functions is done simply and cross-references are generated automatically.
  • By switching a #define you can switch between user documentation (only the official API) and developer documentation (private/non-official functions included). It's also possible to do conditional comments.
    • You don't need defines to do this. Conditional comments work via the ENABLED_SECTIONS part of doxygen config file. --SnakeChomp
  • Doxygen is "prettier". It automatically generates all the documentation formats we care about. It will automatically reference links instead of relying on it being done manually. Easy creation of a more comprehensive index for HTML and CHM help. Can easily create pages that contain "All Event Classes" or "All Control Classes" and etc without requiring manually maintained files for each section listing all member classes.

[edit] Cons

  • David worded it nicely: "If wxWidgets were implemented as a set of platform independent classes with pointers to platform-dependent implementations then Doxygen would make a lot of sense. However, wxWidgets is not implemented this way at all. The reality is that each port (wxMSW, wxMac, wxGTK, etc.) has its own implementation of each GUI class. Thus there is no 1:1 relationship between a class and its documentation because there are several implementations of the same class."
    • Doxygen documentation can exist in multiple places, either opportunistically picked up from files encountered in the source tree or, more commonly, in the header and implementation sources. It is thus perfectly feasible to have platform-specific documentation and generate the documentation with a different config file (as I do for OOFILE). --AndyDent
    • Has anyone considered yet that Doxygen source code is available and that it might be easier to teach Doxygen to properly understand wxWidgets source code than to work the other way round? Just a thought...
  • It's a lot of work to convert the existing documentation to Doxygen (actually we'd need to somehow "backport" the manual in the headers) and someone outside of the core wxTeam would need to do it.
    • This can be automated. Raboof has already made an XML file from the .tex docs, and this file can be converted (relatively) easily into Doxygen format. --SnakeChomp
  • Although helpgen doesn't work correctly, it proves we could also write our own stuff instead of using Doxygen.
    • Doesn't sound convincing to me, I think using (and maybe extending?) existing tools would be to be preferred above introducing yet another kludged together set of scripts. --ARN
  • Depends on Qt for generating stuff.
    • "so what" --ARN, BrianHV
    • On debian, anyway, Doxygen can be installed with no Qt dependency. Only Doxygen-gui depends on Qt. --BrianHV
  • If documentation moves to Doxygen it becomes increasingly difficult for a non-developer to modify it.
    • Not agreed. --ARN
    • Since the documentation is in the sourcefile mentioned on the generated page, it is easy and clear to find/edit. --Goutnet
  • We'd need extra flags in the code to distinguish between "public" functions (i.e., that are part of the API and thus should be in the end-user documentation) and the "internal" functions (i.e., functions that are used internally and might change in future versions of wx)
    • The flag \internal does already exists, just add two config files for Doxygen and that's all --Goutnet
    • No we don't. Private functions and classes can be easily left out of the documentation. See my comment in "Solved Issues" below. --SnakeChomp

[edit] Outstanding Issues

  • Where will the topic overviews, tables of classes by category, and all the other tables we currently have go?
    • You can use the documentation grouping ability of Doxygen to solve that. Does not solve all, but \include does also works if I am right --Goutnet
  • How to document macro-based stuff in wx/dynarray.h, wx/list.h, wx/hashmap.h?
  • Event macros?
  • Differeny files with the same name: AFAIK you can't have both wx/window.h and wx/msw/window.h because doxygen complains about the file being already documented if it sees it for the second time.
    • It doesn't complain about this for me. Version 1.3.9.1 --SnakeChomp
  • Documenting wxButtonBase as if it were a wxButton (If I try that with wxBitmapBase, though, wxBitmap disappears from the docs entirely): 
/**
	@class wxButton
*/
class wxButtonBase {
	[..]
};
    • Possible solution: add a macro definition wxButtonBase=wxButton to the doxygen config file. Doxygen 1.3-rc2 will happily parse both class definitions and _merge_ them. I tried it with wxAppBase and wxApp. --Hajo Kirchhoff

[edit] Solved Issues

  • Hiding deliberately undocumented classes: enclose in #ifndef DOC_DONT_EXTRACT and add PREDEFINED = DOC_DONT_EXTRACT and PREPROCESSING = YES to the doxygen config.
    • This is not a good solution as this definitely makes the code very ugly -- please try to convince me that it also makes it more readable! --VZ
    • Hiding deliberately undocumented classes is alot simpler than what is listed above. If the class X which you do not want to appear in the docs has no Doxygen comment associated with it (member functions can still have Doxygen comments), EXTRACT_ALL = NO, and HIDE_UNDOC_CLASSES = YES, the class will completely vanish from the documentation. If in the future you wish it to appear again, simply add a doxygen comment describing the class, and like magic, it shows up. You can also hide specific functions with this method if you set HIDE_UNDOC_MEMBERS = YES. Is that better VZ? =) --SnakeChomp
  • Fitting the existing "extra" information (like topic overviews) in the doxygen docs.
    • This is done the same way you document classes, you only add a tag indicating this is a manual section (as I did in poEdit's hacker's docs).
  • Doxygen documentation can be placed in either the function declaration or the function definition. This means it can be placed in the .cpp file rather than the .h file, so compilation times would not suffer.
    • Correction: It can be placed absolutely anywhere and does not even need to appear within a source or header file, so the devs themselves would not be affected. --SnakeChomp
  • Doxygen can generate LaTeX, HTML, Man pages, RTF, and XML directly and has postproccessing support for Windows Help, PostScript, and PDF.
  • Doxygen appears able to combine base and window classes into one class quite easily, for instance wxGenericScrolledWindow->wxScrolledWindow and wxWindowBase, wxWindowMSW->wxWindow are both done in this example. My only contribution was to tell it which files to parse, which #defines to use (it doesn't parse #include files), and which class names to combine and switch.
  • Doxygen complains when declarations do not match definitions (e.g. wxUNUSED in one place but not the other). These functions are still documented. This means Doxygen will NOT consider Derived::Foo(T& t) to be derived from Base::Foo(T& WXUNUSED(t)) when it generates the "Reimplemented from/in" list. Doxygen doesn't know what WXUNUSED means unless you tell it. So set PREDEFINED = WXUNUSED(x)=x (for this to work you must also have MACRO_EXPANSION = YES).
  • klaas contributed: PREDEFINED = "WXDLLEXPORT_DATA(name)=name"
  • wxWindow became a parent of wxControl (wxEvtHandler and wxObject as well) after doing a little experimentation. In short, I added some predefines and made them = 1: __WIN32__, __WXMSW__, __WINDOWS__, wxUSE_CONTROLS. --SnakeChomp

[edit] Alternative Approach

Ideally there would be a program that checks the documentation against what's found in the headers and warns of differences in parameters. I don't think Doxygen includes that. --Dimitri

  • No, but it includes an XML output generator which would make writing such program very easy. To be honest, this (using Doxygen as a C++ parser but keep the existing documentation format) is the variant which I like the most by far.
  • Actually, doxygen does do this if I reecall correctly. It will output warnings for undocumented parameters at least - which occur if the parameter is left out of the list; or alternatively if one is documented that does not exist, that also generates a warning.

We could also extend tex2rtf to convert the *.tex files in to "cpp" files. Doxygen does not require that the documentation is in front of the actual definition. It is quite possible to have the class definition in the official cpp files and the documentation in some intermediate file that has been generated by tex2rtf from the *.tex files. Benefits:

  • We can have it both ways: .tex and Doxygen. Doxygen does the merging for us. And there is no need to "backport" the documentation into the source files.
  • We can gradually move from the .tex documentation to the .cpp source documentation if we desire so. No "big bang" neccessary.

For generating whatever format we might want, it might be easier to take an XML-Based Documentation Format

Check the "File Patterns" directive in the Doxygen Config file; you're not restricted to *.h or *.cpp files. I like to use *.dox files to store documentation that does not belong in the sources, but should be there for structure and to fill in details. The *.dox files go in the source directories and you can use the same structuring commands as you do in the source comments. --Bert Put

  • "so what?" --ARN
Retrieved from "http://wiki.wxwidgets.org/Using_Doxygen_For_The_WxWidgets_Documentation"
Personal tools