ubuntu中
sudo apt-get install doxygen doxygen-gui
启动GUI程序
doxywizard
Doxygen formatting conventions
Last modified: October 27, 2009 – 19:12
Doxygen is a documentation generation system. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
There is an excellent Doxygen manual at the Doxygen site. The following notes pertain to the Drupal implementation of Doxygen.
General documentation syntax
To document a block of code, the syntax we use is:
/**
* Documentation here.
*/
Doxygen will parse any comments located in such a block. Our style is to use as few Doxygen-specific commands as possible, so as to keep the source legible. Any mentions of functions or file names within the documentation will automatically link to the referenced code, so typically no markup need be introduced to produce links.
Text formatting (and API parser conformance)
Doxygen directives
/**<br /> * Summary here; one sentence on one line (even if it exceeds 80 chars).<br /> *<br /> * A more detailed description goes here.<br /> *<br /> * A blank line forms a paragraph. There should be no trailing white-space<br /> * anywhere.<br /> *<br /> * @param $first<br /> * "@param" is a Doxygen directive to describe a function parameter. Like some<br /> * other directives, it takes a term/summary on the same line, and a<br /> * description (this text) indented by 2 spaces on the next line. All<br /> * descriptive text should wrap at 80 chars.<br /> * Newlines are NOT supported within directives; if a newline would be before<br /> * this text, it would be appended to the general description above.<br /> * @param $second<br /> * There should be no newline between multiple directives of the same type.<br /> *<br /> * @return<br /> * "@return" is a different Doxygen directive to describe the return value of<br /> * a function, if there is any.<br /> */<br />
Lists
* @param $variables<br /> * An associative array containing:<br /> * - tags: An array of labels for the controls in the pager:<br /> * - first: A string to use for the first pager element.<br /> * - last: A string to use for the last pager element.<br /> * - element: An optional integer to distinguish between multiple pagers on<br /> * one page.<br /> * Any further description - still belonging to the same param.<br /> * This no longer belongs to the param. There should be a newline before this<br /> * paragraph, but it was left out for clarity.<br />
Lists can appear everywhere in Doxygen, but the documentation parser requires to follow a strict syntax to make them appear correctly in the parsed HTML output:
- The list bullet/hyphen is aligned with (uses the same indentation level as) the paragraph before it, no newline before or after the list.
- No newlines between list items.
- Each list item starts with the key, followed by a colon, followed by a space, followed by the key description. The key description starts capitalized.
- If a list item exceeds 80 chars, it needs to wrap, and the following lines need to be aligned with the key (intended by 2 more spaces).
- If there should appear text after the list that still belongs to the block before the list, then it uses the same alignment/indentation as the initial text.
- Again: within a Doxygen directive, blank lines are NOT supported.
- Lists can appear within lists, and the same rules apply recursively.
Links
/**<br /> * @see foo_bar()<br /> * @see ajax.inc<br /> * @see MyModuleClass<br /> * @see <a href="http://drupal.org/node/1354" title="http://drupal.org/node/1354" rel="nofollow">http://drupal.org/node/1354</a><br /> */<br />
The @see directive may be used to link to (existing) functions, files, or URLs. @see directives should always be placed on an own line.
/**<br /> * See also @link group_name Link text @endlink<br /> */<br />
The @link directive may be used to output a HTML link, but also to link to Doxygen groups that are defined elsewhere via @defgroup.
Documenting files
It is good practice to provide a comment describing what a file does at the start of it. For example:
<?php<br />// $Id: theme.inc,v 1.202 2004/07/08 16:08:21 dries Exp $<br /><br />/**<br /> * @file<br /> * The theme system, which controls the output of Drupal.<br /> *<br /> * The theme system allows for nearly all output of the Drupal system to be<br /> * customized by user themes.<br /> */<br />
The line immediately following the @file directive is a summary that will be shown in the list of all files in the generated documentation. If the line begins with a verb, that verb should be in present tense, e.g., “Handles file uploads.” Further description may follow after a blank PHPDoc line.
In general, @file directives should not contain large descriptions, because those are better placed into @defgroup directives, so developers can look up high-level documentation by reading the “group” topic. See http://api.drupal.org/api/groups for a list of API topics/groups.
To add CVS ID-Tags to your file, add a // $Id$ to your file. CVS will automatically expand it to the format shown above. In the future, you don’t have to care about that as CVS will update these information automatically.
For .install files, the following template is used:
/**<br /> * @file<br /> * Install, update and uninstall functions for the XXX module.<br /> */<br />
Documenting functions
All functions that may be called by other files should be documented; private functions optionally may be documented as well. A function documentation block should immediately precede the declaration of the function itself, like so:
/**<br /> * Verifies the syntax of the given e-mail address.<br /> *<br /> * Empty e-mail addresses are allowed. See RFC 2822 for details.<br /> *<br /> * @param $mail<br /> * A string containing an email address.<br /> *<br /> * @return<br /> * TRUE if the address is in a valid format.<br /> */<br />function valid_email_address($mail) {<br />
The first line of the block should contain a brief description of what the function does, limited to 80 characters, and beginning with a verb in the form “Does such and such” (third person, as in “This function does such and such”, rather than second person imperative “Do such and such”). A longer description with usage notes should follow after a blank line, if more explanation is needed. Each parameter should be listed with a @param directive, with a description indented on the following line. After all the parameters, a @return directive should be used to document the return value if there is one. There is a blank line between the @param and @return directives.
Functions that are easily described in one line may omit these directives, as follows:
/**<br /> * Converts an associative array to an anonymous object.<br /> */<br />function array2object($array) {<br />
The parameters and return value must be described within this one-line description in this case.
Documenting hook implementations
Many modules consist largely of hook implementations. If the implementation is rather standard and does not require more explanation than the hook reference provides, a shorthand documentation form may be used:
/**<br /> * Implements hook_help().<br /> */<br />function blog_help($section) {<br /> // ...<br />}<br />
This generates a link to the hook reference, reminds the developer that this is a hook implementation, and avoids having to document parameters and return values that are the same for every implementation of the hook.
/**<br /> * Form builder for the user login form.<br /> *<br /> * @param $msg<br /> * The message to display.<br /> *<br /> * @see user_login_form_validate()<br /> * @see user_login_form_submit()<br /> * @ingroup forms<br /> */<br />function user_login_form(&$form_state, $msg = '')<br />
In order to provide a quick reference for themers, we tag all form builder functions so that Doxygen can group them together. The form builder function is defined as any function meant to be used as an argument for drupal_get_form(). To do this, add a grouping instruction to the documentation of the function. Additionally, while submit, validate and other handlers for the form are not meant to be in this group, you should provide a @see to provide an easy reference to handlers that are attached to the form.
/**<br /> * Form validation handler for user_login_form().<br /> *<br /> * @see user_login_form()<br /> * @see user_login_form_submit()<br /> */<br />function user_login_form_validate($form, &$form_state) {<br /> ...<br />}<br /><br />/**<br /> * Form submission handler for user_login_form().<br /> *<br /> * @see user_login_form()<br /> * @see user_login_form_validate()<br /> */<br />function user_login_form_submit($form, &$form_state) {<br /> ...<br />}<br />
Documenting themeable functions
In order to provide a quick reference for theme developers, we tag all themeable functions so that Doxygen can group them on one page. To do this, add a grouping instruction to the documentation of all such functions:
/**<br /> * Formats a query pager.<br /> *<br /> * ...<br /> *<br /> * @ingroup themeable<br /> */<br />function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) {<br /> ...<br />}<br />
Documenting theme templates
If a template and a preprocess function is used instead of a theming function, an empty function definition of the theme function that is not used should be placed in the contributed documentation (contributions/docs/developer/theme.php).
The template itself should be documented with a @file directive and contain a list of the variables that the template_preprocess_HOOK has prepared for it. If any of these variables contain data that is unsafe to output for XSS reasons, they should be documented; otherwise it can be assumed that variables available have already been appropriately filtered. Anything not listed should not be assumed to be safe to output. It should also contain a @see directive to link back to the preprocessor and the theme_X function.
<?php<br />// $Id$<br /><br />/**<br /> * @file<br /> * Default theme implementation to display a list of forums.<br /> *<br /> * Available variables:<br /> * - $forums: An array of forums to display.<br /> *<br /> * Each $forum in $forums contains:<br /> * - $forum->is_container: Is TRUE if the forum can contain other forums. Is<br /> * FALSE if the forum can contain only topics.<br /> * - $forum->depth: How deep the forum is in the current hierarchy.<br /> * - $forum->name: The name of the forum.<br /> * - $forum->link: The URL to link to this forum.<br /> * - $forum->description: The description of this forum.<br /> * - $forum->new_topics: True if the forum contains unread posts.<br /> * - $forum->new_url: A URL to the forum's unread posts.<br /> * - $forum->new_text: Text for the above URL which tells how many new posts.<br /> * - $forum->old_topics: A count of posts that have already been read.<br /> * - $forum->num_posts: The total number of posts in the forum.<br /> * - $forum->last_reply: Text representing the last time a forum was posted<br /> * or commented in.<br /> *<br /> * @see template_preprocess_forum_list()<br /> */<br />
The template_preprocess_HOOK function should also contain appropriate @see directives.
Documenting contributed modules and themes
- Don’t use
@mainpage. There can be only one @mainpage in the contributions repository, which is reserved for an index page of all contributes modules and themes.
- Use Doxygen Modules (
@defgroup, @ingroup, @addtogroup, see “Limitations and hints” below) sparingly. There are currently over 2,200 module directories in contrib, many of them consisting of more than one module. If each of these modules used just one @defgroup, there would be more than 2,200 entries in the global Module list. If each used more than one …
- If you do use Doxygen Modules, make sure you give them a unique namespace, which would be your module’s name. E.g.
@defgroup views ... for the views.module, @defgroup views_ui ... for the views_ui.module. Don’t use group names which are defined in Drupal core (hooks, themeable, file, batch, database, forms, form_api, format, image, validation, search, etc.).
A recommended way of using Doxygen grouping in contributed modules and themes is the following:
/**<br /> * @defgroup example Example module functionality<br /> * @{<br /> * Longer description of your module's API.<br /> */<br /><br />/**<br /> * Load an example.<br /> * ...<br /> */<br />function example_load() ...<br /><br />/**<br /> * Save an example.<br /> * ...<br /> */<br />function example_save() ...<br /><br />/**<br /> * @} End of "defgroup example".<br /> */<br />
This defines the primary Doxygen group. The syntax is @defgroup [internal_name] [Summary]. The internal name has to be prefixed with the module name (unless it is located in Drupal core’s include files).
Other functions in other files (or even entirely different modules) can then declare @ingroup example to put themselves into the same group.
Limitations and hints
Drupal’s Doxygen processing module, api.module, currently only supports a small subset of all Doxygen commands and makes some assumptions about the formatting of the source. Code to be processed by api.module is advised to stick to these conventions.
Api.module currently supports only one of Doxygen’s three grouping mechanisms: Modules (@defgroup, @ingroup, @addtogroup, @{, @}). When using those, please note the following:
- Modules
work at a global level, creating a new page for each group
. They should be used only to group functions that provide some kind of API, which possibly spans multiple files. Or the other way round: they should not be used to group functions in a file when these functions are only used in that very file. Thats what Member Groups are for (which unfortunately aren’t supported by api.module yet).
@defgroups can be defined only once – trying to define a second @defgroup name with a name already used will result in an error. Use @defgroup name in the “most important” section/file of that group and add to it from other places with @addtogroup / @ingroup.- The
name in @defgroup name Explaination of that group must be single-word identifier, like a PHP variable or function name. Or, as regular expression: [a-zA-Z_][a-zA-Z0-9_]*. Dots, hyphens, etc. are not allowed.
To see how a real Doxygen processes and displays the current Drupal code documentation (both core and contrib), have a look at ax’ Drupal site. Especially, look at the “doxygen error logs” and help improving Drupals code documentation.
Doxygen常用指令介绍
Doxygen注释风格
1 类的申明
/**
* class declaration
*/
2 变量申明
/**< val’s brief. val’s details1. */
3 函数申明
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
|
@file
|
档案的批注说明。
|
|
@author
|
作者的信息
|
|
@brief
|
用于class 或function的简易说明
eg：
@brief 本函数负责打印错误信息串
|
|
@param
|
主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
|
|
@return
|
描述该函数的返回值情况
eg:
@return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
|
|
@retval
|
描述返回值类型
eg:
@retval NULL 空字符串。
@retval !NULL 非空字符串。
|
|
|
注解
|
|
@attention
|
注意
|
|
@warning
|
警告信息
|
|
@enum
|
引用了某个枚举，Doxygen会在该枚举处产生一个链接
eg：
@enum CTest::MyEnum
|
|
@var
|
引用了某个变量，Doxygen会在该枚举处产生一个链接
eg：
@var CTest::m_FileKey
|
|
@class
|
引用某个类，
格式：@class <name> [<header-file>] [<header-name>]
eg:
@class CTest “inc/class.h”
|
|
@exception
|
可能产生的异常描述
eg:
@exception 本函数执行可能会产生超出范围的异常
|
