You are here

Drupal专业开发指南 第21章 为函数编写文档

老葛的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() {
    ...
}

Drupal版本: