七条使用Doxygen生成嵌入式代码文档的注意事项

Doxygen can be an amazing tool for disciplined embedded software developers seeking to quickly generate a software manual that stays in sync with their code. It scans your code, parses out developer comments, and associates the comments with software objects and functions. The resulting output can be in a linked HTML, rtf, or LaTex file that then serves as a body of knowledge for the application. In order to get the most out of Doxygen, though, developers should keep these seven key tips in mind when using the tool. (Note: To follow along with example templates, configuration files, and the like, click here)

 

Tip #1 – Optimize output for C

Doxygen supports many different programming languages and its default won’t necessarily provide the best output for the C language. When using the Doxygen configuration tool Doxywizard, then, developers should select the “Optimize output for C” option. The selection button is located under the mode tab as seen in Figure 1. In the event that C++ is being used, select one of the options to optimize output for C++.

 

Figure 1 – Set the “Optimize output for C” option

Tip #2 – Use module templates for consistent documentation

Doxygen scans the code base looking for comment blocks that start with /** and developers may specify specialized treatment of specific comments by using Doxygen tags within a code block. (Tags are easily spotted because they start with @.) For example, the @file tag will notify Doxygen that the comment that follows provides the module's filename. Figure 2 shows an example of what a comment block with Doxygen tags might look like.

 

Figure 2 – Doxygen comment block

But Doxygen supports over 100 different tags, which means documenting software using Doxygen has the potential to get confusing very quickly. One of the best recommendations for using Doxygen with embedded software is to create a template for header and source files. The template files should contain example code blocks and headers that can then be used during the implementation stage. An example of what the templates could look like can be found here.

Tip #3 – Create a main page

Doxygen will scan any file type that a developer tells it to from within the configuration file, and has the ability to parse a special type of file known as a main page. The main page is a user configurable page that shows up by default when the HTML documentation is loaded or that appears at the start of the generated RTF file. The main page is the perfect place for a developer to describe the project, background, and any coding conventions that might be useful for a reader of the manual to be aware of.

A main page will often describe the following:

 

• What the project is and what its purpose is
• Links to a coding standard
• Links to a C style guide for the project
• Overview of any abbreviations used in the code base
• Version log
• General Doxygen conventions used
• Links to project documents that may be of use
• Useful tools and how they are being used on the project

 

Tip #4 – Use the dot tool from GraphViz

Enabling the dot tool from the GraphViz package provides Doxygen with a very powerful graphing option that will allow a developer to generate graphs such as:

 

• Class diagrams
• Dependency graphs
• Call graphs
• Called-by graphs

 

The dot-generated graphs can provide developers with insights into the software using graphical representations, allowing a quick glance at a pretty picture to provide great insight.

Tip #5 – For HTML, generate the treeview

By default, Doxygen will generate a top menu within its HTML output from which a developer can navigate through the code base. The top menu is helpful, but generating a tree view is a far more efficient method for navigation. The treeview can be created by enabling the option GENERATE_TREEVIEW through the expert HTML tab.

Tip #6 – Don’t add Doxygen to compiler command line

Once a developer starts to use Doxygen it can be tempting to invoke Doxygen through the compiler command line EVERY time a code base gets compiled. Parsing a code base for documentation every compile time is a big mistake, though, because Doxygen can take a “long” time to parse the files and generate the documentation. The time hit can drastically slow down development. Developers instead should create the documentation just before adding any newly developed software to the version control system.

Tip #7 – Do add Doxygen comments to your C style guide

Development teams should be using a C style guide that tells engineers the style conventions to be used during the development process. The style guide should reflect Doxygen templates and conventions in order to provide developers with guidance on how to consistently write comments across an entire code base. Adopting Doxygen should also result in an update to this important development team document.