zohair ahmad » best practices

Posted on 08-26-2007 under best practices, howto, software

We engineers have all been faced with the same predicament at one point or the other. Management types always like to play with buzzwords and make our lives hell. One of the most frequently used ones is “documentation”. Now we can all argue whether documenting code is good or not. Some people may go as far as to say that it is the leading cause of scientific progress and might even yield the cure for cancer some day.

Skepticism (and stupid jokes) aside, there are a lot of different ways one can document one’s code. Heck, I’ve changed from one writing style to another in a matter of weeks, if not days. This snippet’s from last year.
/******************************************************** * check.h * Menu system functions * Fri, 01 December, 2006 * Ver: 01 December, 2006 * A menu system for the project. *********************************************************/
Notice the contrast brought about by the lines of asterisks above and below the comment. This is so that comment blocks should stand out from the rest of the code. Turns out it also made the source code a real pain to read. Also comments in code files don’t make very impressive, presentable documentation, and you still have to write manuals and what not.

Recently I have had the fortune of learning to use doxygen. Doxygen takes your source files as input, processes all your comments and spits out really professional looking documentation in a variety of formats. You can get html, Latex and even pdf outputs (with the right tools of course), although html is more than enough for normal use.

What this means is that all your precious time that you would otherwise have wasted making manuals is now saved. It just takes a bit of practice to learn the special tags that you need to place in your code to help doxygen, and then its a breeze. Here’s an example of the excellent looking documentation you can produce using doxygen.

Installation

Its pretty easy to get started with doxygen. For windows, download and install doxygen and graphviz. For Linux, either download the tarballs, or use your package manager. For Debian do the following
# aptitude install doxygen graphviz
Usage

Installing doxygen also installs doxywizard. You can start this by using the start menu in windows or typing
$ doxywizard
in Linux. ( I would also recommend adding this to your kde or gnome menu). This GUI is pretty useful. It can load your doxyfiles and quickly responds to changes, allowing you to change documentation pretty fast.

I would also recommend downloading the doxygen documentation. (You can view chm files in Linux using Kchmviewer).

Doxygen can work magic but it does need something to go on. There are two things you need to give to doxygen.

First you’ll have to tell doxygen where your source code actually is, and how the documentation is to be generated. This is done using a file called a “doxyfile” which contains a list of assignement statements. Its pretty straightforward if you’ve ever used a config file before. If you haven’t, doxywizard will save your day (you hippy).

Using doxywizard’s “Wizard” or “Expert” options you can choose various options for your documentation. This includes stuff like what’s the projects name, where it’s source code is located, and what type of output you want (tick the “Use dot tool from Graphviz” option in the “Diagrams” tab; you’ll thank me later). Its pretty self-explanatory. You’ll have to save the doxyfile now. I name my files “doxyfile” (amazingly enough). For your first try, since you wouldn’t have used doxygen tags, select “All entities” in the “Mode” tab of the Wizard.

Second you have to have some source code (duh!). You can indicate this in your doxywizard configuration. Right now you dont need to worry about doxytags but we’ll come to it later.

Generating the docs is as easy as hitting the start button. This should usually yield no errors at all, but if there are warnings, they’ll be placed in a text file by the name of warnings.txt. If you generated an html documentation, open index.html in the html directory. See that wasnt too hard was it?.

Using Doxytags

That was pretty bland right. Especially since there was no description on any of the documented elements. Doxygen does recognize whats a function and whats a variable and acts accordingly (the graphs were nice weren’t they?). But it still does not know what you want to say about your code. It doesn’t know what aRandomVar does, does it? You are the only one who can tell doxygen that.

Doxytags are not that hard to learn. Reading the manual a little bit (don’t wince), will get you started very quickly. Basically, any comment that you enclose in a special construct is treated as doxygen comments. Doxygen will search such code blocks for tags. If you have already taken my advice and are using Programmer’s Notepad on Windows, you’ll see that it changes the color of doxygen comments. Also, it highlights doxytags that you use which makes it very easy to write doxygen-friendly comments. If you’re on Linux and using KDE then you’ve got it made. Install KDevelop and everything you need is in there. The default KDE editor (Kate) also does doxygen syntax highlighting.

Once you’ve learned how to tag your comments, you’ll be making professional looking documentation easily. There’s a lot of functionality squeezed into this tool. I’ll leave it up to you to find and use it. For example, how would you add text to your main page, or how to document non-code elements like a communications protocol on a separate page. (You’ll notice that doxygen only generates a page for each code file). You can also change the default stylesheet to make the documentation look like your very own.

This discussion has only touched on changing configuration options using doxywizard. There are loads more options in the doxyfile. This includes the options to remove folder names from your documentation’s file listing. Open doxyfile in an editor, and change the option STRIP_FROM_PATH to the path name that you wanna remove from your documentation. Check out all the other options as well.

Best Practices

This post is my first entry to the new category I’ve named “Best Practices”. Using doxygen not only helps you in generating documentation, it is also a very good way of writing standard comments. Its practically an industry standard. Most of the open source code you’ll find contains doxygen tags. So its not just an option to learn them, it could well be a necessity. Adding doxytags to your code, makes it very easy for someone else to run doxygen on it, if they can’t get your standard documentation. So using doxygen is a good practice, and should be adopted whenever you write code.

There are some more best practices I would like to share. Keep watching this space.

best practices

Recent posts

Recent comments

Pages

Links

Social

Meta

Categories