+44 (0) 207 193 0834

Doxygen and best practices

So what is doxygen?

Pulled from Wikipedia, the official definition.

"Doxygen is a documentation generator for the programming languagesC, C++, C#, Fortran, Java, Objective-C, PHP, Python, IDL (CORBA and Microsoft flavors), VHDL, and to some extent D. It runs on most Unix-like systems, Mac OS X and Windows.

The first version of Doxygen borrowed some code from an old version of DOC++; later, the Doxygen code was rewritten by Dimitri van Heesch.

Doxygen is a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code."

More useful reading here

Ok, sounds all good but why do we need to use it? Having been a PHP programmer for a couple of years now and on the drupal platform for a period of time I have seen my share my fair share of badly written code. I have been guilty of it myself at times, just understanding the code you have written or just out of pure lazyness perhaps? Things include not commenting lines of code, declaring variables, bit of a developers nightmare when you are picking up someone elses code! Having watched an excellent talk at Drupalcon London this talk got me thinking about best practices.

So how does doxygen come into all this? Well the way I see it, it's a useful way of reading well documented code in a reference. So if I were to look into a whole codebase of a project and wanted to find a useful custom function I wrote or even a hook for something then I would know where to look. Doxygen also provides us a useful base for writing good quality code whether it's procedural stuff or in OO.

What is the syntax/best practices to use?

In this case it all comes down to the quality of code you write. As a guide, follow this documentation here or go to http://www.cisst.org/resources/software/cis/doxygen-documentation.html.

The basics:

  • Use doxygen commenting in the .h (include) files of your code
  • Use the /*! sequence to indicate the start documentation blocks and */ to indicate the end of commenting. The same rules apply when ever you start a documentation block you must close it and be careful not to place source code within these documentation blocks. If one text line is sufficent for documentation use //!. Inbetween the start of a documentation block, the use of asterisks is optional at the beginning of each line.

Classes for OO:

  • Use the /*!before the declaration of a class to provide some descriptive information about the class.
  • Use the \brieftag to provide a short one line brief description of the class.
  • Use the \sa (See Also) keyword to link to related variables, methods, or classes. This is the equivalent command to \see tag. The command sets the next section to trigger a link to anything that might possibly be a keyword and also in the html document creates the phrase "See Also:" followed by the linked parameters.
  • Use the \ingroup to specify which group this class's documentation should be grouped under. Refer to the section on Grouping below.
/*! \brief classB: A normal class
  \ingroup common
  This class likes bob.
  This class is part of the group common.
  This class inherits class A  
  \sa classA 
 */
class classB: public classA{
...

File listing:

At the top of every .h file (except for template and inline files) after the cvs header, one should place a \filetag to label the file. The syntax actually takes in a filename as a parameter and can use the \briefbut for our purposes this is not required
for example one should use:

 
/*! 
  \file 
  \brief
  \ingroup tracking 
 */

For the erc libraries, the requirement is the use of \filewithout any arguments, \briefto give a short blurb on the purpose/contents of the file and a \ingroupwith the group to which the file belongs to in order to link this file's documentation to the group. The \file listing must be used or else documentation for the #define's and the typedefs will not be used.

/**
 * Summary here; one sentence on one line (should not, but can exceed 80 chars).
 *
 * A more detailed description goes here.
 *
 * A blank line forms a paragraph. There should be no trailing white-space
 * anywhere.
 *
 * @param $first
 *   "@param" is a Doxygen directive to describe a function parameter. Like some
 *   other directives, it takes a term/summary on the same line and a
 *   description (this text) indented by 2 spaces on the next line. All
 *   descriptive text should wrap at 80 chars, without going over.
 *   Newlines are NOT supported within directives; if a newline would be before
 *   this text, it would be appended to the general description above.
 * @param $second
 *   There should be no newline between multiple directives (of the same type).
 * @param $third
 *   (optional) TRUE if Third should be done. Defaults to FALSE.
 *   Only optional parameters are explicitly stated as such. The description
 *   should clarify the default value if omitted.
 *
 * @return
 *   "@return" is a different Doxygen directive to describe the return value of
 *   a function, if there is any.
 */

A typical documentation block

/**
 * My example connectors function example checking to see if a and b exist the doing some stuff.

*
 * @param $name
 *   The name of the string being passed in and called at module level when returned.

*/

function connectors($name) {

  // Check connector_one matches to A or connector_two matches to B

  if ((connector_one == 'A') || (connector_two == 'B')) {

    // Variable name of string

   $name  = 'example-name';

  }

}

Doxygen would pick this up as a function call and the developer picking this up would quickly identify why it's there and what it's doing.

So by doing Drupal development work for the past few years I thought a full proof module to help me achieve this clean coding practice is the coder module.

Two benefits:-

  1. If you are pushed for time and need to have well documented code, run this through as a project (will update this in a bit to reflect how to achieve this) and coder will automatically tidy it up for you.
  2. Or if you are like me and want to figure it why the hell your code is poor work through each bug and it will help you improve in the longrun.

So how do I run doxygen on one of my projects?

  1. If you have ubuntu run sudo apt-get install doxygen or download tar gzip/installer from here or go to http://www.stack.nl/~dimitri/doxygen/download.html
  2. Download Matt Farinas excellent file from here or go to https://github.com/mattfarina/drupal-6-doxygen and put this into your drupal root directory
  3. CD to the directory you want to doxygen
  4. Next on command line execute doxygen drupal.doxy
  5. Once its finished compiling navigate to your html docs so it could be something http://sitename/docs/html/index.html

So as an overview use Doxygen as a great developers guide for any documentation you have written for specifically custom written functionality and use the Coder module to help you achieve those best coding standards in Drupal.

Indy's picture
07 Oct 2011
Indy

Add new comment