Doxygen
Table of Contents
This page will attempt to describe the best practice for documenting aegisub source code.
Please take the time to read the URLs in the Command section as well as this entire page.
Commands
We will be using the / method for Doxygen comments. with all commands prefixed with a @.
Any block starting with a /// will be parsed as a Doxygen comment, if it a local comment that does not require exposure using the usual // comment will ensure it is not parsed by Doxygen.
There are a few pages that you should read, please read them completely.
- Documentation Blocks
- How to actually document your code, there are sections that are specific to C++ and others for unrelated languages, feel free to skip those.
- Lists
- Generating lists in the final documentation.
- Commands
- Commands that can be used in the documentation, remember that we're using @ and not for commands.
There is a section for Custom Commands, any custom command can be added if it will make documenting the source easier. There are no real limits here, feel free to add any commands and commit them to the Doxygen config file.
Featured Commands
There are some commands we should use where possible, which can be very handy over time.
- @attention - Words of note.
- @bug - Use this if there is a bug in the following block. Use this in place of XXX: or FIXME:
- @exception or @throw - Use these when you're documenting an exception or throw.
- @todo - Items that that need to be implemented or completed in the future.
- @warning - Something of note to anyone using the code.
@todo and @bug can be split off onto their own pages with back references, this makes things easy if we ever want to go back and fix any of these issues.
Custom Commands
Not a part of Doxygen but ones we've added ourselves for the sake of convenience.
- @ticket - "@ticket{<id>}" will link to a corresponding ticket in the bug tracker.
- @revision - "@revision{<rev>}" will link to the changeset in trac.
Where
List of where documentation should be placed for each situation encountered.
The following should be placed above where it is located in each file:
- Class
- Definition
- Enum
- Namespace
- Struct
- Typedef
- Union
- Variables
- Both private and public, variables that are local to a function don't need to be documented using doxygen but should have a short comment if it's pertinent to it's usage.
API vs Source
If the source is a library that exposes a real API, all documentation should go into the header not the source. Otherwise all documentation should go into the source itself.
Function
Each function should have the absolute bare minimum shown below.
/// @brief [brief description of the purpose, keep this short!] /// @param [name of param] [description] /// @param ... /// @return [what this function returns] (only required if the function returns anything) /// /// [detailed description] (this may be omitted if the brief description explains everything required.
Feel free to extend this as much as you want, the abve is a bare minimum only.
File
Each file should have a description as to it's purpose, we'll be using a general layout for each file:
[LICENCE BLOCK] /// $Id$ /// @category <categories this file falls into> /// /// Purpose of this file
The space between the license block and the Doxygen block is important. The $Id will be substituted using svn:keywords Id.
Output
The output of the final documentation can be modified in many ways. If you want a custom page or a different layout feel free to commit to the config file or ask verm.
Examples
Some examples of how to document various bits of code.
Enumeration
enum { a, /// description b, /// description c /// description };
or
enum { /// description a, /// description b, /// description c };
