Let's Use Doxygen

[Malaclypse]

So far, a skeletal documentation has been added to any header file. Some files are partially documented, some only have the skeleton by now. This needs to be finished next.

 

Currently any undocumented function has this documentation header in front:

/*!
* \ingroup <group>
* \brief
*
*     Detail
*
* [\param <parm> <desc> (where applicable, for any parameter)]
* \return None|<type>
*/

The ! in the first line of the comment inidicates this as a special block to doxygen and gets processed. Ignore the \ingroup tag for now, this gets covered later.

The \brief tag should contain a short one-liner of what the functions does. You can refer to the name of any parameter <parm> using the syntax \a <parm>. That is, assume we have a function declaration like void foo(int i) you can refer to parameter i using \a i. For example

\brief foo increases \a i by 1

 

After this comes a text block with a more detailed in-depth description of the function. You can use the \a tag here as well to refer to function arguments. Additionally you can use a \see <ref> tag to refer to any function, variable and data type that is documented. Assuming, void bar() is declared (and documented) elsewhere you can use \see bar to include a link to the documentation of this function.

 

The list of \param tags must match the function's signature excluding return-type. It's a doxygen error if they do not match. The <desc> might be empty and the <parm> must match the name of the argument. The foo function therefore needs a line

\param i desc for i

in the comment block.

 

The syntax of the \return tag is \return <desc>. Currently we use the term None if the return type is void. Instead of using \return <type> we should use the syntax \retval <type> <desc> if the functions return-type is anything but void.

 

After \return there can be additional tags. Commonly used is a list of \sa <ref> tags (meaning "see also") that links to related documentation. If the function's behaviour is more complex, a \callgraph tag should be added here too. If you want to add more advanced documentation ask me about what you want to do, I might be able to help, or look at your local doxygen documentation.

 

 

Most global variables aren't documented yet. We want to document them after their declaration using the special C comment block

extern int global_var; /*!< description of variable */

Note the extra !< characters at the begin of the comment. You can refer to other variables, functions and data types using \see or \sa tags here too. This is also the way how members of data types likes structs or enums get documented, although this has mostly been done.

 

 

All documentation is grouped in modules (also called Modules on the generated documentations navigation bar). The tag \ingroup <group> tells to add the documentation for this function to the group <group>. You can get a list of all groups by looking at the generated modules page. If you hover the links, strip of the "group__" from the filename and replace any double underscore "__" with a single underscore "_" you get the name of the group that you can refer to. The groups are defined in the file docs/groups.doxy. The grouping of functions isn't finished yet, that is, not any function is known to be in the group it belongs to.

 

 

To build all the graphs, generated by default, you need to have graphviz installed. You can disable this by using either doxywizard or by changing the HAVE_DOT line in docs/Doxyfile, in case you can't have graphviz installed for whatever reason. Global callgraph support is subject to change, for this reason it's important to add a \callgraph tag to any applicable function.

 

 

All documentation is currently subject to review. Devs are encouraged to document the functions they know well, where possible and take part in the review of the documentation.

 

Any support is welcome. If you want to add to this subject, feel free to pm me either in this forum, or pm any of my in-game chars

Edited February 24, 2005 by Malaclypse

[Malaclypse]

Small update:

 

Some missing data types and variables have been documented and committed. Now all functions, macros and data types should have been documented. Some variables are still not documented yet.

 

If you find any error feel free to contact me via this forum, or via PM (forum or ingame).

[Grum]

OMFG, mala, you're great! You even documented all the new files (for which I was too lazy myself )

[Malaclypse]

Lol Grum , you were lucky they contain only very few declarations