Hello,
I really feel like I should share a quick guide on how to document your code with doxygen and I will explain why! (Doxygen just because its the one I use)
Many programmers, especially beginners, tend to not document the code at all, and use little or no comments in the code. Its not always imperative to use them, but it certainly doesn't make any harm and can be precious in many cases!
When projects start to grow bigger, the codebase starts to expand and it becomes harder and harder to maintain the complexity without proper documentation.
Most people underestimate this, but if you write a big chunk of code and leave it abandoned for some months, when you look at it, it won't even look like it was done by you. Many times, you just feel like refactoring it again, because you don't remember what was on your mind when you made it.
And remember that some projects are big enough that you are away from a "module" of your project months, just while working intensively on another module.. It gets that big often!
For maximum efficiency when working on your software projects, being them libraries, games or general applications, I recommend a lot of comments here and there and organized code. Just think that you will be needing it later, eventually.
But the purpose of this post is exactly to tell you quick and dirty how to write a nice documentation with doxygen syntax. Just follow the topics for what you want and you will be fine.
Please note that doxygen will by default parse documentation on header files only, which is where you normally make the documentation!
After you are done documenting your code, you can run the doxygen GUI application to generate the HTML automatically. Like a sir!
Documentation comment
In C++ you normally make block comments /* ... */ and line comments // ... , doxygen will ignore these and only parse block comments as /** ... */ and line comments as /// ...
Making a series of line comments will generally work as a single block comment.
Documentation indicators
When documenting your code structures, inside the doxygen comment blocks, you usually need to denote what specific detail you are documenting.
For that, doxygen accepts a few indicators, which I will explain next, that
may be started with \ and(or) @.
Document a file
To describe a file you may make a doxygen comment, as stated previously, anywhere in that file, as follows:
/**
\file header.h
This file is all about doing.. hmmm. stuff.
*/
Then it will appear in the file listing of the documentation page.
Document a module
.. Also called a group, it allows you to make groups with your structures, so you can easily denote what belongs where. In its simplest form, you can define a group anywhere like this:
/**
\defgroup Graphics
This module contains all graphics related classes.
Cool text here to look like a mr. fancy coder.
*/
Document a class
It is a good practice to document things like a class, a variable, a method, etc by making a comment exactly before it appears in the header file. It is very desirable to follow that practice, both because it looks really neat and because in some cases doxygen will simply know what you are trying to document, without specifying it, just because it comes next. This is important.
Now the example:
/**
\ingroup Graphics
\class MyClassName
\brief This is a short description, which is shown in the class list in the documentation page.
This is a more detailed description, with a lot of details about my class.
\author I am the author!
\date when i made it!
\see MyOtherClass
@author Also works to tell who did it!
*/
class MyClassName{};
The \ingroup will make sure the class belongs to Graphics module from the previous example. You may include a class in many groups.
The \see line will make a link pointing to the other class documentation page.
I think it explains itself if you read the example, but it will become cleared as you advance the tutorial.
Document a method(function)
Something you probably will be doing a lot is to explain what your functions does, and what should be in mind when using it. Following the rule of documenting the method before it appears, check the example:
/**
\brief Counts the child nodes of a tree node
A more detailed description.
\code
A C++ suggested usage.
\endcode
\param recursive Whether the call is recursive and therefore counts each child's child count.
\return an int with the count
*/
int countNodes(bool recursive);
As you may see, you can use \brief to define the "headline" of what your function is for.
Then, you may describe your function's ways. The \code ... \endcode block will force a C++ like presentation in the document page, with proper indentation and highlight of the snippet.
Document a namespace
You can give detail about each namespace you declare, just simply as:
/**
\namespace global_namespace
All things in the library go into this namespace.
*/
namespace global_namespace{}
Document notes and warnings
Usually when documenting something, you may want to leave a note, with more highlight, so the reader pays attention:
/// \note my note
And other times, it is really imperative that the user gets your message, so you highlight a warning:
/// \warning CAREFUL WITH THE EGGS!
Document a "to-do"
When you are documenting a function or anything else, you may suddenly remember it lacks something, or there is just a detail that needs changing, whatever, but you can't do it right now.
When that happens, you may leave a todo note, and there will be a page in the documentation with all things that are left undone, as specified by you. To leave a todo note, just do:
/// This function is very crazy
/// \todo Complete this function support for eating brains of farmers
void func();
Document a page
In the documentation HTML, you find an entrance page, that you may use to write anything you want as an introductory page. It is important to fill this in to give details about the software.You can do it:
/**
\mainpage My Software main page
Now you're writing content to the entrance page..
You can add sections like:
\section Overview Overview
And now this is under a cool header title.
*/
Besides the main page, you can create other pages named as you want, which will go under Related Pages tab in the documentation HTML. It is pretty much the same, but change the indicator you use.
/**
\page FAQ
The most frequently asked questions and its answers.
*/
Finish
After reading this, I recommend that you do some experiments to get confortable with using it.
Just go to
http://www.stack.nl/~dimitri/doxygen/ and start your journey, its a funnier task to do than you may think.
This was a really simplified guide, but if you think anything is wrong, missing or lacking, just inform me and I will change it!
