Advanced Configuration File Setup

The wizard tab within DoxyWizard allowed us to quickly get Doxygen up and running.However, there are many customizable options which can be used that are only available from within the Expert tab.So before we begin talking in detail about how to work with our source files, we’ll first explore a few very useful options that are available to expert users.

The JAVADOC_AUTOBRIEF option under the project topic enables Doxygen to recognize the first line of a comment as the brief description. This allows us to save time by not explicitly specifying brief command within our commands. Therefore, we will always assume that the first line of a statement is a brief overview.

The Expert input topic has some very useful features which allow us to override our default inputs that were generated by the wizard. We can specify individual source directories, in addition to specifying file patterns such as *.c, setting an image directory and other options that the developer may find helpful. We can also exclude files and directories and specify filtering schemes that Doxygen should use on the inputs.

By default Doxygen does not generate a navigational frame.The navigational frame displays on the left hand side of the HTML page and allows us to navigate anywhere within our html document without having to jump through hoops in top menu.In order to display this framed navigation, under the HTML topic in DoxyWizard, the GENERATE_TREEVIEW option must be selected.

Finally, the Dot topic allows us detailed control over our graphs.We can specify the dot font, control image format using DOT_IMAGE_FORMAT, specify directories, the look and the maximum number of nodes which can be generated within a graph.

With these updates to the configuration file the output generated by Doxygen will be more refined.At this point we can begin development of our code but first, we are going to build a MainPage for our documentation that will provide anyone reading the documentation an overview and instructions on how to use the documentation.This will provide an overview of some useful tags which can be used when we document code.

PDFs

PDF documents cannot be directly generated using Doxygen; however, there is a simple method to create one once the LaTex documentation has been generated.Within a command window (like I said I pretend there is no use for command prompts) navigate to the /latex folder and type $make.The result will be a PDF document named refman.pdf located in the /latex folder.

Generating a Mainpage

When someone opens our documentation we would like for them to see a table of contents with a series of web links that they can then use to navigate to useful information about the project and the source code. As a general summary, what types of things would someone want to see on the mainpage? After some thought and a few restful nights of sleep (luckily this question wasn’t thought provoking enough for me to lose any sleep), I’ve decided to add the following items to my mainpage

– Introduction (what is this whole thing about?)

– Version Log (what version is this and how have things changed from version to version)

– Acronyms ( what do all these funny terms mean?)

– API’s (Do we have any api’s for drivers that need to be explained?)

– Coding Standard (what are our code conventions? How do we name things)

– Documentation (how we documented things)

– Project requirements (a quick overview of what we had to do)

– Testing and Validation (how did we prove that this version actually works)

– Tools ( tools that we used to develop the project such as compiler, ide, lint, svn etc)

To create our mainpage we are going to name a text file overview .txt and put everything we need in it for our mainpage.We’ll have to make sure that wherever we place the overview document that it is in the doxygen path for source files.We will look at the major tags that are used here but please see the example template for a fully functional version.

While developing the mainpage there were two primary methods that could be used to create the effect of the table of contents.The first was to lump the entire table of contents data into a single file (overview.txt).The second was to create subpages in separate files which Doxygen would then combine.The second option was of interest primarily because it would allow for a nice modular table of contents structure.However, it also added complexity to the table of contents that might go above and beyond a basic user so at this point I have decided to keep it simple and use the single file method.Don’t be surprised though if I create a follow up to this article explaining how to create a paged table of contents.

We start our mainpage by simply using the mainpage command within a comment block at the top of overview.txt.Within the HTML documentation we can use any HTML tags.For our purposes, the most useful of these are listed in Table 1.We use the anchor commands to create anchors directly above each of our table of content sections.We will then create a link to each of those anchors within the table of contents.When the link is clicked, the documentation will jump to that anchor.In order to keep the document looking clean, we will also want to use the horizontal rule tag to create a horizontal line in between each of our sections.It may also be necessary to occasionally force a carriage return within the documentation.To do this we will use the <br> tag.

HTML Command	Description
<A NAME=”Contents”></A>	creates an anchor
<A HREF=”#Introduction”>Introduction</A>	creates a link to an anchor
<br>	creates a carriage return on the html page
<hr>	creates a horizontal line

Table 1: HTML Commands

In order to create our table of content sections we will use Doxygen’s section command. If we find that one of our sections should be broken up into smaller sections we can also make use of the subsection command. This will allow us to organize our mainpage and properly control the flow of information.

As with any document, we will want to include images throughout our documentation because an image is worth a 1000 words. Wherever we want to include an image all we need to do is use the doxygen image tag. This tag consists of the command image, a type such as html, rtf or latex and then the file name such as image.jpg. It is important to note that latex images must be Encapsulated PostScript (eps). If it isn’t, good luck but most likely it will not display at all or it will display itself wrong. This does mean that if you are inserting an image and want to generate html, rtf and latex files that three separate image tags will be required in order to have the image display in all three formats.

Finally, one of the most useful commands is for creating a bulleted list.To create a bullet before an item in a bulleted list simply place a – in front of it.For a complete table of contents template, see the associated resource files which can be downloaded from www.beningo.com/resources/doxy-110123.zip.

Documenting the code

After all the effort that has gone into Doxygen, we are finally ready to understand how to document our code.In order to jump start this and future efforts, I have included in the resources for this article two module templates.The first, is a *.h template which contains commonly used types for documenting C header files.The second is a *.c template which contains commonly used types for documenting C source files.The general principles in these files can generally be carried over to other languages but they have been created and tested for use within an embedded C environment.

The first thing that we do when we are documenting a module is to include the file command so that Doxygen can know what file module this is.If you remember back to our configuration file, we included JAVADOCS_BRIEF so that the first line of our comment in a file would act as the overview for the file.The following comment can be placed at the top of a module to generate both file and brief information.Just remember that the brief statement requires that the first statement end with a period (.).

/** file physics.h

* This file contains the header definitions for the physics application.

*

Within most modules we have common types of “objects” such as labels, macros and variables.Each of these is very easy to document and all three are documented in exactly the same way.The key is to simply put /** and then anything afterwards will automatically document the variable.For example, the following code segment documents a label named METRIC_G.

/**

* Used to define the acceleration of gravity in m/s^2

*/

#define METRIC_G 9.81

Documenting an enumeration, typedef, structure is not much more complicated. The description is defined the same as in the label. However, a detailed description of a member can be added by simply adding /**< Description*/ afterwards where description is the description of the member. The < character is used to tell doxygen that the comment is associated with the variable that was declared before this comment. If you really want, you can explicitly specify the difference between an enumeration and struct by placing a enum orstruct command in front of the definition but Doxygen does such a great job of knowing what it is documenting that it is really unnecessary and not recommended. An example of documenting a struct can be found below:

/**

* Defines two variables which specify the spacecraft structure.

*/

typedef struct

{

uint8 Acceleration;/**<Rate at which the spacecraft is accelerating */

uint8 Mass;/**< The current mass of the spacecraft */

}SpaceCraft_Type;

The most complicated embedded types to document are functions. This is because of the relative complexity that can be associated with them. They have input and return parameters in addition to references to other functions that are associated with them. That is why it is extremely useful to create a function template that can be copied, pasted and modified for each new function that is developed.

When documenting a function is useful to break it up into two separate sections using the section tag.The first section is a Description section.It contains an overview of what the function is, what it does and why it is used.In addition, param and return commands can be used to specify all of the parameters that are passed to and from the function.The second section is an example section.In this section we use a command code to create a code block within doxygen.We can then type in example code on how the function is used in an application.When the example is completed we use the endcode command to leave the code block mode.Finally, if this function is a single function within a module of functions it is useful to create a link to all of the other related functions.This can be done by using the see command followed by the name of the function that we wish to link to.An example template for documenting a function can be found in the resources for this article as well as below.

/******************************************************************************

* Function : Sys_Init

*//**

* section Description Description:

*

* This function is used to initialize the system.

*

* param None.

*

* return None.

*

* section Example Example:

* code

*

* endcode

*

* see App_Init

******************************************************************************/

In addition to documenting variables and functions, Doxygen can also document todo’s within the code.This can be done by using the following format:

/**
* todo description here.
*
*/

Conclusions:

During the shortened development cycles that exist today, keeping documentation up to date and accurate is extremely challenging.Managers expect software engineers to develop code quickly, bug free and with lots of documentation.Unfortunately these three things are at odds with each other.

Doxygen allows us to focus on the job at hand and auto-generate our documentation so that when the boss is standing over us, we no longer have to be concerned that we’ll get bitten later by documentation.

In this article we have reviewed Doxygen and stepped through the process of setting up and configuring it.The result was the development of a number of templates and a project directory which can be used to jump start your next software project.