PHP 文档标准

WordPress 使用从 PHPDoc 中汲取灵感的自定义文档模式,PHPDoc 是一种不断发展的标准,用于为 PHP 代码提供文档,由phpDocumentor维护。

应该记录什么

WordPress 中的 PHP 文档主要采用格式化文档块或内联注释的形式。

以下是 WordPress 文件中应记录的内容的列表:

  • 函数和类方法
  • 班级
  • 类成员(包括属性和常量)
  • 要求并包括
  • 钩子(动作和过滤器)
  • 行内评论
  • 文件头
  • 常量

记录技巧

语言

摘要应该清晰、简单和简短。避免描述元素存在的“原因”,而是专注于记录它“做什么”和“何时”做某事。

函数、钩子、类或方法是_第三人称单数_元素,这意味着应该使用_第三人称单数动词来描述每个元素的作用。_

提示:
需要帮助记住如何结合第三人称单数动词吗?想象一下在函数、钩子、类或方法摘要前加上“It”:

  • :“(它)做某事。”
  • :“(它)做某事。”

总结例子:

  • 功能:功能是做 什么的?
    • 好:显示帖子的最后修改日期。
    • 错误:显示帖子的最后修改日期。
  • 过滤器:过滤了 什么?
    • 好:过滤帖子内容。
    • 不好:允许您编辑在帖子模板中输出的帖子内容。
  • 动作: 动作 什么时候触发?
    • 好:_在大部分核心加载完成后触发,并且用户已通过身份验证。
    • 坏:_允许您在加载大量 WordPress 核心后注册自定义帖子类型、自定义分类法和其他一般内务处理任务。

语法

描述性元素应该写成完整的句子。该标准的一个例外是文件标题摘要,其目的是作为文件“标题”而不是句子。

在摘要、描述和参数或返回描述中列出元素时,应使用连续(牛津)逗号。

各种各样的

@since:搜索添加到 WordPress 的版本时推荐使用的工具是svn blame. 旧挂钩的附加资源是WordPress 挂钩数据库。

如果使用这些工具后无法确定版本号,请使用@since Unknown.

从 WPMU 移植过来的任何东西都应该使用@since MU (3.0.0). @since MU (3.0.0)不应更改现有标签。

代码重构:允许将记录的特定操作或过滤行隔开以满足编码标准,但不要重构文件中的其他代码。

格式指南

笔记:
WordPress 的 PHP 内联文档标准是专门为在官方代码参考中获得最佳输出而量身定制的。因此,遵循如下所述的核心和格式标准对于确保预期输出_极为重要。_

一般的

DocBlocks 应该直接放在挂钩、动作、函数、方法或类行之前。DocBlock 和声明之间不应有任何开始/结束标记或其他内容,以防止解析器变得混乱。

概括

摘要中不应使用任何类型的 HTML 标记或 Markdown。如果文本引用 HTML 元素或标签,则应将其写为“图像标签”或“img”元素,而不是“ <img>”。例如:

  • Good:在页眉中打印链接标签时触发。
  • 错误:在标头中__打印标签时触发。<link>

可以使用内联 PHPDoc 标签。

描述

HTML 标记永远不应在代码示例之外使用,但可以根据需要在描述中使用 Markdown。

  1. 清单:

    使用连字符 (-) 创建无序列表,前后各有一个空行。

     * Description which includes an unordered list:
     *
     * - This is item 1.
     * - This is item 2.
     * - This is item 3.
     *
     * The description continues on ...

使用数字创建有序列表,前后各空一行。

     * Description which includes an ordered list:
     *
     * 1. This is item 1.
     * 2. This is item 2.
     * 3. This is item 3.
     *
     * The description continues on ...
  1. 代码示例将通过将代码的每一行缩进 4 个空格来创建,前后各有一个空行。代码示例中的空白行也需要缩进四个空格。<pre>请注意,以这种方式添加的示例将在标签中输出,而_不是_语法高亮显示。
     * Description including a code sample:
     *
     *    $status = array(
     *        'draft'   => __( 'Draft' ),
     *        'pending' => __( 'Pending Review' ),
     *        'private' => __( 'Private' ),
     *        'publish' => __( 'Published' )
     *    );
     *
     * The description continues on ...
  1. URL 形式的链接,例如相关的 Trac 票证或其他文档,应使用标记添加到 DocBlock 中的适当位置@link
     * Description text.
     *
     * @link https://core.trac.wordpress.org/ticket/20000

@since部分(变更日志)

每个函数、钩子、类和方法都应该有一个与之@since关联的相应版本(更多内容见下文)。

标签的描述中不应使用 HTML @since,但必要时可以使用有限的 Markdown,例如在变量、参数或参数名称周围添加反引号,例如$variable.

版本应以3位数的x.x.x形式表示:

 * @since 4.4.0

如果对函数、挂钩、类或方法进行了重大更改,@since则应添加其他标签、版本和描述以提供该函数的更改日志。

“重大变化”包括但不限于:

  • 添加新的参数或参数。
  • 必需的参数变为可选。
  • 更改默认/预期行为。
  • 函数或方法成为新 API 的包装器。
  • 已重命名的参数(一旦宣布支持 PHP 8.0)。

@since出于这个明确的原因,PHPDoc 在 DocBlocks 中支持多个版本。在块中添加 changelog 条目时@since,应引用版本,并应在句子大小写和形式中添加描述并以句点结尾:

 * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.

其他说明

@param, @type, @return: 不应在这些标签的描述中使用 HTML,但可以根据需要使用有限的 Markdown,例如在变量周围添加反引号,例如$variable.

  • 内联@see标签也可用于在核心中自动链接挂钩:
    • 钩子,例如'save_post'
    • 动态挂钩,例如'$old_status_to_$new_status'(请注意,引号内已删除任何多余的花括号)
  • 默认值或可用值应使用单引号,例如“草稿”。可翻译字符串应在描述中标明。
  • HTML元素和标签应该写成“音频元素”或“链接标签”。

换行

DocBlock 文本应在 80 个字符的文本后换行到下一行。如果 DocBlock 本身在左侧 20 个字符位置缩进,则换行可能发生在位置 100,但不应超出总共 120 个字符的宽度。

文档块格式

下面每个部分中提供的示例显示了预期的 DocBlock 内容和标签,以及确切的格式。在 DocBlock 中使用空格而不是制表符,并确保每个标签组中的项目根据示例对齐。

1. 函数和类方法

函数和类方法的格式应如下所示:

  • 摘要:简短的一句话解释函数的用途,最多跨越两行。在末尾使用句点。
  • 描述:对摘要的补充,提供更详细的描述。在句子末尾使用句号。
  • @ignore:当元素仅供内部使用并且应该从解析中跳过时使用。
  • @since x.x.x: 应始终为 3 位数(例如@since 3.9.0)。例外是@since MU (3.0.0)
  • @access:仅用于仅核心函数或实现“私有”核心 API 的类。如果该元素是私有的,它将输出一条消息,说明其供内部使用的意图。
  • @see:对内部高度依赖的函数、方法或类的引用。请参阅上面关于预期格式的内联标签的注释@see
  • @link: 提供更多信息的 URL。这绝不应该用于引用另一个函数、钩子、类或方法,请参阅@see
  • @global:列出在函数或方法中使用的 PHP 全局变量,以及可选的全局描述。如果列出了多个全局变量,它们应该按类型、变量和描述对齐,彼此作为一个组。
  • @param: 注意说明前参数是否为_Optional_,并在末尾加句号。描述应提及可接受的值以及默认值。例如:可选。这个值做了一些事情。接受“post”、“term”或空的。默认为空。
  • @return:应该包含所有可能的返回类型,以及每个类型的描述。在末尾使用句点。注意:@return void不应在默认捆绑主题之外使用。
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */

1.1 数组参数

作为参数数组的参数应仅记录在“原始”函数中,并通过相应 DocBlock 中的标记进行交叉引用@see

数组值应该使用 WordPress 的散列符号风格来记录,类似于Hooks 的记录方式,每个数组值以@type标签开头,并采用以下形式:

*     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)

“原始”函数和参数数组重用的一个示例是wp_remote_request|post|get|head().

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 * @param type  $var Description.
 * @return type Description.
 */

在大多数情况下,不需要将散列符号中的单个参数标记为_可选_,因为整个数组通常是可选的。指定“可选”。在散列符号描述中应该足够了。在数组不是可选的情况下,单个键/值对可能是可选的,并应标记为必要。

1.2 弃用的功能

如果该功能已弃用并且不应再使用,@deprecated则应添加标签以及版本和使用内容的描述。请注意标签的额外使用@see——代码参考使用此信息来尝试链接到替换功能。

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 * @deprecated x.x.x Use new_function_name()
 * @see new_function_name()
 *
 * @param type $var Optional. Description.
 * @param type $var Description.
 * @return type Description.
 */

2. 班级

类 DocBlocks 的格式应如下所示:

  • 摘要:简短的一句话解释课程的目的,最多两行。在末尾使用句点。
  • 描述:对摘要的补充,提供更详细的描述。在末尾使用句点。
  • @since x.x.x: 应始终为 3 位数(例如@since 3.9.0)。例外是@since MU (3.0.0)
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 */

如果记录子类,包含@see对超类的标记引用也很有帮助:

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Super_Class
 */

2.1 类成员

2.1.1 属性

类属性的格式应如下所示:

  • 摘要:在末尾使用句号。
  • @since x.x.x: 应始终为 3 位数(例如@since 3.9.0)。例外是@since MU (3.0.0)
  • @var: 格式与 相同@param,但可能会省略说明。
/**
 * Summary.
 *
 * @since x.x.x
 * @var type $var Description.
 */
2.1.2 常量
  • 摘要:在末尾使用句号。
  • @since x.x.x: 应始终为 3 位数(例如@since 3.9.0)。例外是@since MU (3.0.0)
  • @var: 格式与 相同@param,但可能会省略说明。
/**
 * Summary.
 *
 * @since x.x.x
 * @var type $var Description.
 */
const NAME = value;

3. 要求和包括

所需或包含的文件应与摘要描述 DocBlock 一起记录。get_template_part()可选地,为了清楚起见,这可能适用于内联调用。

/**
 * Summary.
 */
require_once( ABSPATH . WPINC . '/filename.php' );

4. 钩子(动作和过滤器)

action 和 filter hooks 都应该记录在调用do_action()or do_action_ref_array(), or apply_filters()or之前的行中apply_filters_ref_array(),格式如下:

  • 摘要:对钩子用途的简短的一行解释。在末尾使用句点。
  • 说明:如果有必要,对摘要的补充说明。
  • @ignore:当钩子仅供内部使用并且应该从解析中跳过时使用。
  • @since x.x.x: 应始终为 3 位数(例如@since 3.9.0)。例外是@since MU (3.0.0)
  • @param:如果参数是参数数组,请使用散列符号记录每个参数(在上面的数组参数_部分_中描述),并在每行末尾包含一个句点。

请注意,它_不_@return用于挂钩文档,因为操作挂钩不返回任何内容,而过滤器挂钩总是返回它们的第一个参数。

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Short description about this hash.
 *
 *     @type type $var Description.
 *     @type type $var Description.
 * }
 * @param type  $var Description.
 */

如果钩子位于 HTML 块或长条件语句的中间,则 DocBlock 应放在 HTML 块或条件语句开始之前的行上,即使这意味着连续强制换行/PHP 标记HTML 行。

搜索添加挂钩的版本时使用的工具是svn blame,或用于旧挂钩的WordPress 挂钩数据库。如果在使用这些工具后无法确定版本号,请使用@since Unknown.

4.1 复制钩子

有时,钩子会在同一个或不同的核心文件中多次使用。在这些情况下,不是每次都列出整个 DocBlock,而是仅完整记录操作或过滤器的第一个添加或最逻辑放置的版本。后续版本应该有单行注释。

对于行动:

/** This action is documented in path/to/filename.php */

对于过滤器:

/** This filter is documented in path/to/filename.php */

要确定应记录哪个实例,请搜索多个相同的挂钩标签,然后svn blame根据最早的修订版查找挂钩的首次使用。如果在同一个版本中添加了多个挂钩实例,请将最合乎逻辑的一个记录为“主要”。

5.内联评论

方法和函数中的内联注释格式应如下所示:

5.1 单行注释

// Allow plugins to filter an array.

5.2 多行注释

/*
 * This is a comment that is long enough to warrant being stretched over
 * the span of multiple lines. You'll notice this follows basically
 * the same format as the PHPDoc wrapping and comment block style.
 */

重要说明:多行注释不能以/**(双星号)开头,因为解析器可能会将其误认为是 DocBlock。请改用/*(单个星号)。

6.文件头

文件头 DocBlock 用于概述文件中包含的内容。

只要有可能,所有WordPress 文件都应包含标题 DocBlock,而不管文件的内容如何——这包括包含类的文件。

/**
 * Summary (no period for file headers)
 *
 * Description. (use period)
 *
 * @link URL
 *
 * @package WordPress
 * @subpackage Component
 * @since x.x.x (when the file was introduced)
 */

摘要部分旨在简要描述文件的具体用途

例子:

  • 好:“小部件 API:WP_Widget类”
  • 坏:“核心部件类”

描述部分可用于更好地解释文件的概述信息,例如特定文件如何适合 API 或组件的整体构成_。_

例子:

  • 好: “Widgets API 由_WP_Widget__和__WP_Widget_Factory__类组成,此外还有各种实现 Widgets 和相关侧边栏 API 的顶级功能。默认情况下,WordPress 会注册一些常见的小部件。”_

7.常量

常量DocBlock用于给出常量的描述,以便更好的使用和理解。

常量的格式应如下所示:

  • 摘要:在末尾使用句号。
  • @since x.x.x: 应始终为 3 位数(例如@since 3.9.0)。例外是@since MU (3.0.0)
  • @var: 格式与@param. 描述是可选的。
/**
 * Summary.
 *
 * @since x.x.x (if available)
 * @var type $var Description.
 */

PHPDoc 标签

WordPress 中使用的常见 PHPDoc 标签包括@since@see@global @param@return(完整列表请参见下表)。

在大多数情况下,标签的使用是正确的,但并非总是如此。例如,有时您会看到@link内联标记,链接到单独的函数或方法。不需要“链接”到已知的类、方法或函数,因为代码参考会自动链接这些元素。对于内联“链接”挂钩,正确使用的标签是@see——参见_其他描述_部分。

标签

用法描述
@access私人的仅在有限的情况下使用,例如当代码中不能使用可见性修饰符时,并且仅在私有时使用,例如仅用于核心功能或实现“私有”API 的核心类。直接在块中的行下方使用@since。
@deprecatedversion xxx 改用替换函数名函数/方法被弃用的 WordPress 版本。使用 3 位版本号。应附有匹配@see标签。
@global数据类型 $变量描述记录函数/方法中使用的全局变量。对于布尔和整数类型,分别使用bool和int。
@internal信息串通常用于包装{}以添加仅供内部使用的注释。
@ignore(独立)用于跳过整个元素的解析。
@link网址链接到函数/方法的附加信息。对于外部脚本/库,链接到源。不用于相关功能/方法;改用@see。
@method返回类型说明显示在类中找到的“魔术”方法。
@package包裹名字指定文件中所有函数、包含和定义所属的包。在文件顶部的 DocBlock 中找到。对于核心(和捆绑的主题),这始终是WordPress。
@param数据类型 $变量描述函数/方法参数的格式:参数类型、变量名、描述、默认行为。对于布尔和整数类型,分别使用bool和int。
@return数据类型说明记录函数或方法的返回值。@return void不应在默认捆绑主题之外使用。对于布尔和整数类型,分别使用bool和int。
@see元素名称引用函数/方法所依赖的另一个函数/方法/类。仅应内联用于“链接”挂钩。
@since版本 xxx添加了文档发布版本功能/方法。使用 3 位版本号——这有助于版本搜索,以及在代码中比较版本时使用。例外是@since MU (3.0.0)。
@static(独立)注意:此标记过去曾使用过,但不应再使用。只需在代码中使用 static 关键字就足以让 PHP5+ 上的 phpDocumentor 识别静态变量和方法,并且 PhpDocumentor 会将它们标记为静态。
@staticvar数据类型 $变量描述注意:此标记过去曾使用过,但不应再使用。记录静态变量在函数/方法中的使用。对于布尔和整数类型,分别使用bool和int。
@subpackage子包名对于页面级的DocBlock,指定文件中所有函数和定义的Component。对于类级别的 DocBlock,指定类所属的子包/组件。
@todo信息串记录对尚未实施的元素的计划更改。
@type参数数组值的数据类型描述用于表示参数数组值类型。有关示例语法,请参阅Hooks或Parameters That Are Arrays部分。
@uses类::方法名() / 类::$变量名/函数名()注意:此标记过去曾使用过,但不应再使用。引用使用的关键函数/方法。可能包括一个简短的描述。
@var数据类型说明类变量的数据类型和简短描述。回调被标记为回调。

笔记:
PHPDoc 标签与一些文本编辑器/IDE 一起工作,以显示有关一段代码的更多信息。对于使用这些编辑器的开发人员了解其目的是什么以及他们将在代码中的什么地方使用它很有用。PhpStorm 和 Netbeans 已经支持 PHPDoc。

以下文本编辑器/IDE 具有您可以安装的扩展/捆绑包,它们将帮助您自动创建 DocBlock:

  • Notepad++:Notepad++ 的 DocIt (Windows)
  • TextMate:php.tmbundle (Mac)
  • SublimeText:sublime 包(Windows、Mac、Linux)

注意:即使在生成 DocBlock 的帮助下,大多数代码编辑器也不会做非常彻底的工作——您可能需要手动填写任何生成的 DocBlock 的某些区域。

弃用标签

**前言:**目前,为了保持一致性,WordPress Core 将继续使用@subpackage标签——无论是在编写新的 DocBlocks 还是编辑旧的 DocBlocks 时。

只有当新的 - 外部 - PSR-5 建议最终确定时,才会考虑全面的更改,例如弃用某些标签。

正如新的 PSR-5建议中所提议的那样,应弃用以下 PHPDoc 标签:

  • @subpackage(赞成统一的包装标签@package Package\Subpackage:)
  • @static(不再需要)
  • @staticvar(不再需要)

其他标签

@package插件和主题中的标签(不包括捆绑的主题)

第三方插件和主题作者不得@package WordPress在其插件或主题中使用。插件的名称@package应该是插件名称;对于主题,它应该是主题名称,用下划线隔开:Twenty_Fifteen

@author标签

WordPress 的政策是不使用该@author标签,除非在外部库中维护它。我们不想暗示对代码的任何类型的“所有权”,这可能会阻碍贡献。

@copyright@license标签

和标签用在外部库和脚本中,不应该用在 WordPress 核心文件中@copyright@license

  • @copyright用于指定外部脚本版权。
  • @license用于指定外部脚本许可证。