Fast Doxygen Howto
This is an ugly fast howto for doxygen main usages, you should close this page and read the official documentation instead.
A specific documentation of the commands that we are going to look are available at http://www.doxygen.nl/commands.html
You are more than welcome to edit this document and to modify it, and to add features on this small howto
Introduction
Maybe the highest lack that EFL has is the documentation of the API and the big problem about this is that's not easy to maintain the API documentation up to date, also, it is very easy to modify a function and do not update their related documentation.
All these problems are solved with Doxygen, because doxygen is mainly just comments in the source code that in a result, you can build all the documentation needed (html pages, manpages, pdf's, etc) up to date with the code. It is very hard and even impossible to not have the api documented to day with the code using Doxygen.
For a final point, let me say that this reading should be obliged for anybody that write code, it is very handy for everybody and for himself to have the api documented correctly. Will be nice if there's some rules with things like nobody can add a new function without write its doxygen documentation or nobody can modify a piece of code without add its related doxygen documentation if doesn't has it.
Let's Start
In order to add Doxygen-specific comments, basically you just need to add an extra comment character, I'm not going to explain in detail that because you are not stupid, so let's directly continue with the howto :)
Main Page
Your documentation needs a main page, of course, let's put it on your main header file, or your main source code file, in our example will be Eina.h
/** * @mainpage Eina * @author Myself * @date 2009 * * @section section_toc Nice TOC Title * * <ul> * <li> @ref eina_container_subsec * <ul> * <li> @ref eina_array_subsubsec * ... * The data types that are available are * @li array * @li hash table * ... * @subsection eina_container_subsec Containers * Containers are data types and ... where foo is the @ref eina_stringshare_subsec. * ... * Take a look at the @ref tutorial_error_page. * @todo add debug function
Note that the first line starts with /, this means that these comments are parsed by doxygen
On this example you can see that we define the name of the main page as Eina and other not-so-important values, after we have a new section @section to define our table of contents with some html-beautify on it, the @ref are just reference's (links) to other sections/subsections/page/anchor, just like in our section_toc name. The sections ends when a new section (or another main element like @page) is reached or when the comment block finishes.
The @li call does nothing more than to show the elements as a list
You can add a @subsection and write some text, this will be viewed like a (sub)section in the formated page, and acts like an anchor if you reference to it using @ref, you can also use @subsubsection too
With the @ref you can point anywhere of your documentation elements (linkable), so you can create a special link to a tutorial page for example
The @todo call is very nice because not only you list your TODO points in that page (if is included on this page) but also remember all your TODO calls and show you the full list if you click on it
Specific Extra Pages
Suppose that you want to write a tutorial, you should include it in the file where the source code about this example tutorial, this is an example:
/**
* @page tutorial_error_page Error Tutorial
*
* @section tutorial_error_introduction Introduction
*
* The Eina error module provides a way to manage errors in a simple
* but powerful way in libraries and modules. It is also used in Eina
* ...
* Here is an example of use:
*
* @code
* #include <stdlib.h>
* #include <stdio.h>
* @endcode
* Of course, instead of printf(), eina_log_print() can be used to
* have beautiful error messages.
*/
With @page you define that this section is a separated page, on this example there's the @code call where you can include some code for your documentation, it will has directly fancy colors as syntax :)
Note that all the pieces in your code that is described with doxygen (like function names, macros, etc) is directly available as a link
Functions
For define your function you need to add the @brief call that is a short description, the @param call that is the definition of the parameters of your function, the @return that is the value returned, and the rest of text is the full description
When you want to say that foo is a pointer, use @p for it
- Use @see foo when you want to add a See also: reference
- @deprecated use foo() instead is used to say to something is deprecated, pointing the reader to the new correct one
/** * @brief Register a new error type. * * @param msg The description of the error. It will be duplicated using * strdup(). * @return The unique number identifier for this error. * * This function stores in a list the error message described by * @p msg. The returned value is a unique identifier greater or equal * than 1. The description can be retrieve later by passing to * eina_error_msg_get() the returned value. * * @see eina_error_msg_static_register() */ EAPI Eina_Error eina_error_msg_register(const char *msg) { Eina_Error_Message *eem;
Groups
With @addgroup Lib_Foo_Group Foo you add all the rest of the code to the group Lib_Foo_Group until reaches the end of the group, so all the following code will be included on a specific group, like the lib of foo, so like:
/** * @addtogroup Eina_File_Group File * * @brief Functions to traverse directories and split paths. * ... * @{ */ #ifndef _WIN32 struct dirent *de; DIR *d; ... /** * @} */
Notice the @{ and the @}
