Page MenuHomePhabricator

Doxygen
Updated 2,083 Days AgoPublic

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 **,,

References

Examples

  • source:/trunk/eina/src/include/Eina.h
  • source:/trunk/eina/src/include/eina_error.h
  • source:/trunk/eina/src/lib/eina_error.c

Imported from https://trac.enlightenment.org/e/wiki/Doxygen
History:
1 Thanatermesis 2009-10-09 10:13:56
2 Thanatermesis 2009-10-09 11:05:01
3 scrappy 2011-05-26 09:03:56

Last Author
beber
Last Edited
Sep 5 2013, 2:42 PM
Projects
None
Subscribers
None