Mac OS X Porting - Code Documentation

Contributors

• Mox Soini: Mox

Introduction

As described by Matthias Mueller-Prove from Sun OpenOffice.org team, different mediums have different purposes and advantages (first and second blog entry).

OpenOffice.org Wiki is good for Work-in-Progress documentation and when trying to capture high-level descriptions for the OpenOffice.org architecture and functionality. Easy and quick collaboration by editing wiki is much better way than editing static webpages, which can be accessed by much fewer people (and require the knowledge to code HTML and use CVS).

However, when documenting the code at function level (i.e. describing each function), it is VERY important that the documentation is intimately tied to the code, not elsewhere in some hard-to-guess url. When documentation is in the code, it also has the best chances to stay up-to-date with the changes in the code. Function documentation MUST stay up-to-date or it is hindering coding, not helping.

Any diagrams of code structure must also be generated dynamically, to ensure that the diagrams are always up-to-date.

Doxygen and Javadoc -style comments

So how can the above requirements be fulfilled? Well, there is the widely used and standard tool for this: Doxygen. It allows us to do even very complex documentation if needed.

While Doxygen has it's (default) own format for creating function documentation, it also supports JavaDoc -style of documentation. The JavaDoc -style is the preferred one for OpenOffice.org, because it allows us to have consistent documentation style for both Java and C/C++ code. Note that JavaDoc -program (itself) can only be used for .java source files, this is the reason to use Doxygen instead.

Using Doxygen

For Mac OS X, you can download Doxygen from [1]. It includes also a GUI with which you can relatively easily create documentation yourself.

When using the Wizard:

 1) give a name to the project, and a version
 2) give source folder (code) and destination folder (for the documentation)
 3) in the "Mode" -tab, set "desired extraction mode:" to "All entities"
 4) in the "Output" -tab, use HTML only, it's faster that way
 5) in "Diagrams" you can choose "No Diagrams", if you do not want to have UML -like class diagrams. 
    It's faster that way too.
 6) Close Wizard and then go to "Expert..." and in the first "Project" -tab enable JAVADOC AUTOBRIEF.
 7) Ok, now you can generate the documentation :) You can view it by opening index.html in your browser.

Documentation for the use of Doxygen is available on the Doxygen webpage

For an example of OpenOffice.org documentation with Doxygen, see the Canvas -module (milestone 202 with cws cairoquartz01) and especially the cairo canvas, Surface class -documentation

The vcl -module can be read too. It has the Diagrams enabled.

Code documentation style

To provide consistent style, please put the function documentation to the SOURCE file (e.g. salfoo.cxx or salfoo.c), NOT in the header file (e.g. salfoo.h)

While more details can be seen in the documentation, the following example should show you all the important things you need. Look at the stuff between /** and */.

While the code below shows how you write documentation, you should look e.g. at cairo_cairo.cxx about what should be written in the documentation.

 /** 
  * A test class. A more elaborate class description. 
  */ 
 
 class Test 
 { 
 
 public: 
 
 /** 
  * An enum. 
  * More detailed enum description. 
  */ 
 enum TEnum { 
   TVal1, /**< enum value TVal1. */ 
   TVal2, /**< enum value TVal2. */ 
   TVal3 /**< enum value TVal3. */ 
 } 
 
 *enumPtr, /**< enum pointer. Details. */ 
  enumVar; /**< enum variable. Details. */ 
 
 /** 
  * A constructor. 
  * A more elaborate description of the constructor. 
  */ 
 Test(); 
 
 /** 
  * A destructor. 
  * A more elaborate description of the destructor. 
  */ 
 ̃Test(); 
 
 /** 
  * a normal member taking two arguments and returning an integer value. 
  * @param a an integer argument. 
  * @param s a constant character pointer. 
  * @see Test() 
  * @see  ̃Test() 
  * @see testMeToo() 
  * @see publicVar() 
  * @return The test results 
  */ 
 int testMe(int a,const char *s); 
 
 /** 
  * A pure virtual member. 
  * @see testMe() 
  * @param c1 the first argument. 
  * @param c2 the second argument. 
  */ 
  virtual void testMeToo(char c1,char c2) = 0; 
 
 /** 
  * a public variable. 
  * Details. 
  */ 
 int publicVar; 
 
 /** 
  * a function variable. 
  * Details. 
  */ 
  int (*handler)(int a,int b); 
  
  };

Current and Future work

The javadoc-style documentation has been started, but more focused effort is needed. The examples in actual code can be seen in at least:

• CWS cairoquartz01: canvas/source/cairo/ (Mox Soini and others)
• CWS aquavcl01: vcl/aqua/source/gdi/salatslayout.cxx (Sébastien Plisson)

Future goal is to have dynamically created documentation of the core OpenOffice.org modules in the web, with updates in every milestone, or even daily. While very small part of the code has javadoc-style comments, doxygen still creates the code structure documentation automatically :)