老葛的Drupal培训班 Think in Drupal
函数文档应该使用下面的语法：
/**
* Short description, beginning with a verb.
*
* Longer description goes here.
*
* @param $foo
* A description of what $foo is.
* @param $bar
* A description of what $bar is.
* @return
* A description of what this function will return.
*/
function name_of_function($foo, $bar) {
...
return $baz;
}
简短描述的开头，应该使用现在时态的祈使动词，比如“Munge form data”（“混合标单数据”）或“Do remote address lookups”（执行一个远程地址查找）（而不是“Munges form data” 或“Does remote address lookups”）。让我们看一个来自于Drupal核心的一个例子，它位于system.module中：
/**
* Add default buttons to a form and set its prefix.
*
* @ingroup forms
* @see system_settings_form_submit()
* @param $form
* An associative array containing the structure of the form.
* @return
* The form structure.
*/
function system_settings_form($form) {
...
}
在前面的例子中有一些新的Doxygen结构体:
• @see告诉你可参考哪些其它函数。前面的代码是一个表单定义,所以@see指向了表单的提交处理器。当API模块解析这个注释来生成文档时（比如http://api.drupal.org中可用的文档），它将把@see后面的函数名转换为一个可点击的链接。
• @ingroup将一组相关的函数联系到了一起。在这个例子中，它创建了一组提供表单定义的函数。你可以创建你想要的任意的小组名字。可能的核心值有：batch, database, file, format, forms, hooks, image, menu, node_access, node_content, schemaapi, search, themeable, 和validation。
提示 你可以在http://api.drupal.org查看一个给定组的所有函数。例如，表单构建器函数位于http://api.drupal.org/api/group/forms/6，而可主题化的函数位于http://api.drupal.org/api/group/themeable/6。
实现普通的Drupal结构体的函数，比如钩子函数或表单验证/提交函数，可以完全省略@param和@return语法，但是仍然应该包含一行描述函数功能的说明，如下面的例子所示：
/**
* Validate the book settings form.
*
* @see book_admin_settings()
*/
function book_admin_settings_validate($form, &$form_state) {
...
}
}
如果一个函数是一个菜单回调（也就是，使用hook_menu()映射到一个URL上），那么最好能加以说明：
/**
* Menu callback; print a listing of all books.
*/
function book_render() {
...
}
为钩子实现编写文档
当一个函数是一个钩子实现时，此时不需要为钩子编写文档。简单的说明一下实现了哪个钩子就可以了，例如：
/**
* Implementation of hook_block().
*/
function statistics_block($op = 'list', $delta = 0, $edit = array() {
...
}
