×
Namespaces

Variants
Actions

Generate source code documentation with Doxygen

From Nokia Developer Wiki
Jump to: navigation, search
Article Metadata
Compatibility
Platform(s):
Symbian
Article
Created: lfd (22 May 2007)
Last edited: hamishwillee (08 May 2013)


Contents

Overview

Programmers code but most of the time forget to document the code properly. Difficulties are not immediate but if one has to continue some existing work or if you have to upgrade some script written a year ago, I seriously doubt that you'll remember what all your classes do, which arguments you have to pass to the functions and what they return...

This article shows briefly how to generate good quality documentation with as less effort as possible.

I'm using Doxygen to the generate my documentations.

Installation

GraphViz is a wonderful tool for generating graphics.

With Linux I didn't have to do anything all executable are set automatically. With windows you have to give the path to the GraphViz binaries, LaTeX binaries...


Tags quick overview

Here are some of the most common tags, but I invite you to check the command list reference.

  • Inform author for class, method, function, file...
@author
  • Add a bug. A separated bug page can be later generated with links
@bug
  • Inform date for class, method, function, file...
@date
  • Put some source code between those 2 tags. Notice that the syntax is automatically highlighted
@code
@endcode
  • File documentation.
@file
  • With this tag you can write text for the main page, add section, subsection, :paragraph... Latex users will find some similarities here.
@mainpage
@section
@subsection
@subsubsection
@paragraph
@...
  • Package documentation.
@package
  • Method, function parameter documentation
@param
  • Method, function return value documentation
@return
  • Add a todo task. A separated todo page can be later generated with links
@todo
  • Inform version for class, method, function, file...
@version
  • Add a warning. A separated warning page can be later generated with links
@warning


Settings file

First launch

You need to give a settings file to the executable with all the instructions. A good start is to use the wizard in the Doxygen GUI, set the paths, chose what kind of graphics you want to generate... Then try to compile and see the output.


Expert mode

The expert mode of the Doxygen GUI will give you much more choices to generate custom documentation. Here are few tricks

Project

  • Check JAVADOC_AUTOBRIEF: with it option the dot at the end of a description marks the delimiter with brief and detail description ex:
## The application Foo class. <-- brief description
# This class does that and that and that. <-- detailed description
class Foo( object ):
def __init__(self):
pass #...
  • unchecking FULL_PATH_NAMES will output foo.py instead of /home/user/workspace/wiki/foo.py


Build

  • EXTRACT_ALL check: you have everything (private, static, local....)in source code documentation.


Input

  • in INPUT you can choose which files of the project have to be documented. With our example I set /home/user/workspace/wiki/foo.py in input instead of the whole /home/user/workspace/wiki/ folder.
  • you can apply filters...


Source browser

  • with INLINE_SOURCES the function, method... declaration is inserted below it description


HTML

  • in this section you can give your custom CSS header and footers.
  • here you also give the path to the CHM compiler.
  • to considerably enhance the navigation check GENERATE_TREEVIEW. You'll then have a tree menu on the left part of the page.


LaTeX

  • you can here customize your LaTeX layout, give extra package (like language for example)
  • it is a good idea to check PDF_HYPERLINKS and USE_PDFLATEX


Dot

  • here is where you configure that diagram outputs like image format, resolution....
  • if you check UML_LOOK, it will generate the UML diagrams from the source.


Code documentation example

Let's take the singleton example.

## @file foo.py
# Singleton implementation example
 
## @package foo
# Foo.
# @author LEFEVRE Damien
# @date 22/05/2007 19:38:19
# @version 0.1
 
## @mainpage Foo documentation
# @section intro_sec Introduction
# Short script to demonstrate the use of doxygen.
#
# @section license_sec License
# Copyright 2006-2007 @em LEFEVRE @em Damien (contact at lfdm.net)
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
 
## Singleton class.
# Singleton implementation example.
class Foo( object ):
## Stores the unique Singleton instance.
_iInstance = None
 
## Class used with this Python singleton design pattern.
# @todo Add all variable method need to this Singleton class below.
class Singleton:
## The constructor.
# @param self The object pointer.
def __init__(self):
## a foo class variable.
self.foo = None
 
## The constructor.
# @param self The object pointer.
def __init__( self ):
# Check whether we already have an instance
if Foo._iInstance is None:
# Create and remember instanc
Foo._iInstance = Foo.Singleton()
 
# Store instance reference as the only member in the handle
self._EventHandler_instance = Foo._iInstance
 
 
## Delegate access to implementation.
# @param self The object pointer.
# @param attr Attribute wanted.
# @return Attribute
def __getattr__(self, aAttr):
return getattr(self._iInstance, aAttr)
 
 
## Delegate access to implementation.
# @param self The object pointer.
# @param attr Attribute wanted.
# @param value Vaule to be set.
# @return Result of operation.
def __setattr__(self, aAttr, aValue):
return setattr(self._iInstance, aAttr, aValue)
 
if __name__ == "__main__":
# create a first object
a = Foo()
# get and print class variable foo
print a.foo
# create a second object
b = Foo()
# set a string to the class variable foo
b.foo = "Hello Folks"
# create a third object
c = Foo()
# get and print class variable foo for object a
print a.foo
# get and print class variable foo for object c
print c.foo

With Python classes, functions, variable descriptions always start with ##. Notice also that the @ is replaced by \ with Java or C++.

  • At first are documented file and package. We add the author of the document, date and version.
  • Then we create the main page which will have Foo documentation as title, an introduction and a license section.
  • If JAVADOC_AUTOBRIEF is checked, "Singleton class" will be the Foo class brief description and "Singleton implementation example" the detailed one.
  • The static class variable "_iInstance" declaration also start with a ##.
  • In the Singleton class documentation, there will be a @todo tag.
  • Now lets have a look at __getattr__ definition.
    • 1st line: brief description
    • 2nd & 3rd lines: parameters description
    • 4th line: return value description
  • ...


Conclusion

Once you have played around and found a Doxygen configuration that matches the best your requirements, keep it as a draft and only change the paths and input files.

The effort to produce this code documentation is minimal. Like we saw before, Doxygen generate HTML pages, PostScript, LaTeX, RTF... So there should be a solution for everybody depending if one wants to have a compiled help, PFD or Microsoft document...

This page was last modified on 8 May 2013, at 06:59.
210 page views in the last 30 days.
×