CommunityDoxygenProject
Doxygen is a source code documentation tool that parses raw source code and generates (among other formats) navigable, indexed HTML documentation from the raw source files. Code comments using the Javadoc comment style are used to build information about classes, structs, enums, files, and more. This allows newer developers to quickly find out information about how various structures in the code base are related to one another.
The Community Doxygen Project aims to accomplish the following:
- Have community members collaborate with MySQL developers to "doxygenate" the MySQL source code, enabling proper and full source documentation of the entire code base
- Enable community members interested in the MySQL source code to "get their feet wet" in the source by learning about the various subsystems and subsequently documenting them
- Provide other developers with a fabulous tool they themselves can use in adding plugins and new features to the MySQL community edition
Contents |
[edit] How To Join The Project Team
We have set up a mailing list on the MySQL Mailing List Server. If you are interested in contributing to the project, feel free subscribe to this list.
[edit] Current Project Team Members
- Jay Pipes
- David Shrewsbury
- Frank Mash
- Ronald Bradford (arabxptyltd)
- Baron Schwartz (xaprb)
- Nicklas Westerlund
- Steven Zimmer
[edit] Doxygen Commenting
The Javadoc style is used to "trigger" doxygen into considering the comment block as something which should be parsed into the overall documentation output. Below, you'll find an explanation for the comment commands that will be used in the MySQL source code.
Note that you should not use any other comment commands without first checking in with the team to ensure that command is appropriate to use. Also note that we use the @-style of command syntax, not the \-style. See the doxygen online manual for more information about the two styles.
[edit] Class and Function Documentation Commands
- @brief
- the words after contain a brief description of the class or function purpose
- @details
- the following words contain a more detailed description of the class or function purpose
- @return
- describes the behaviour of the return (not the type of the return, since that information is already auto-documented by code inspection from doxygen
- @retval <return-value>
- describes one return value for the function. multiple @retval commands may be used to document multiple return values.
- @param <param-name> <description>
- describes the name of the parameter and a description of its purpose
- @see <related-item>
- describes a related class, file, namespace, or function
- @note
- comments about usage, summary, etc
- @example <example-file>
- directs doxygen to include the specified file as an example of usage for the function or class
- @todo
- marks that more work should be done. these command comments are automatically grouped into a TODO list in the output. If you see TODO in the source code, be sure to turn it into an appropriate @todo command. Any comments flagged with XXX should also be @todo.
- @file [<name>]
- Starts a comment block for the entire file. One example where this may be needed is to document TODO items that are not associated with one particular function.
- @bug
- Used to document known bugs.
- @code ... @endcode
- Marks a block of text with sample code within a comment. C/C++ keywords will be highlighted.
- @verbatim ... @endverbatim
- Marks a block of text that is included verbatim. This may prove useful with some long descriptions of some functionality.
- @warning
- Document a warning within a comment.
[edit] Grouping Commands
[edit] The Doxygen Source Browers
OK, so the first doxygen source browsing is available here: http://dev.mysql.com/sources/doxygen/mysql-5.1/index.html.
There are a number of things that are missing from the browseable documentation; notably good comments about what the classes do, how they logically interrelate, how they are used, and more. That's where this team comes in. Gradually, as we doxygenate the code base, this documentation and source browser will fill out.
[edit] Source tree
There is a separate BitKeeper clone of the current MySQL 5.0 tree that will be used to apply the patches prior to merging them into the main tree. It is available as mysql-5.0-doxygen from http://mysql.bkbits.net/ .
[edit] Current Priority Code Sections
The development team has identified the following sections that we should tackle first:
mysys strings include client
[edit] Configuration File Used
Here is a link to the configuration file used to generate the documentation.