JavaScript 文档标准

WordPress 遵循内联 JavaScript 文档的JSDoc 3 标准。

应该记录什么

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

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

• 函数和类方法
• 对象
• 闭包
• 对象属性
• 要求
• 事件
• 文件头

记录技巧

语言

简短的描述应该清晰、简单和简短。记录“什么”和“什么时候”——很少需要包括“为什么”。如果需要，“为什么”可以放在长篇描述中。例如：

函数和闭包是_第三人称单数_元素，这意味着应该使用_第三人称单数动词_来描述它们的作用。

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

• 好：“（它）做某事。”
• 坏： “（它）做某事。”

功能：功能是做什么的？

• 好：处理 X 元素上的点击。
• 坏：包含在 X 元素的反向兼容中。

@since：搜索添加到 WordPress 的版本时推荐使用的工具是svn blame.

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

代码重构：当文档发生变化时，不要重构文件中的代码。

语法

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

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

格式指南

应遵循以下准则以确保可以正确解析文档块的内容以包含在代码参考中。

简短说明：

简短描述应该是一个句子，不包含任何类型的标记。如果描述涉及 HTML 元素或标签，则应将其写为“链接标签”，而不是“”。例如：“在页眉中打印链接标签时触发”。

详细说明：

如果需要，可以在长说明中使用 Markdown。

@param和@return标签：

这些标签的描述中不允许使用 HTML 或 markdown。HTML元素和标签应该写成“音频元素”或“链接标签”。

换行

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

对齐注释

相关的评论应该间隔开，以便它们对齐，使它们更容易阅读。

例如：

/**
 * @param {very_long_type} name           Description.
 * @param {type}           very_long_name Description.
 */

功能

函数的格式应如下所示：

• 摘要：对函数用途的简短一行解释。在末尾使用句点。
• 描述：对摘要的补充，提供更详细的描述。在末尾使用句号。
• @deprecated x.x.x: 仅用于已弃用的函数，并提供该函数被弃用的版本，该版本应始终为 3 位数字（例如@deprecated 3.6.0），以及要使用的函数。
• @since x.x.x: 初始介绍应为 3 位数（例如@since 3.6.0）。如果进行了重大更改，@since则应添加其他标签、版本和描述以作为更改日志。
• @access：仅在私有时用于函数。如果该函数是私有的，则它仅供内部使用，并且在代码参考中不会有它的文档。
• @class：用于类构造函数。
• @augments：对于类构造函数，列出直接父类。
• @mixes：列出混合到对象中的mixins。
• @alias：如果此函数首先分配给一个临时变量，这将允许您更改记录它的名称。
• @memberof：如果 JSDoc 无法自动解决此问题，则此函数包含在其中的名称空间。
• @static：对于类，用于标记一个函数是类构造函数上的静态方法。
• @see: 依赖的函数或类。
• @link: 提供更多信息的 URL。
• @fires: 函数触发的事件。与特定类关联的事件应列出类名。
• @listens：此函数侦听的事件。事件必须以事件名称空间为前缀。与特定类关联的事件应列出类名。
• @global: 将此函数标记为要包含在全局命名空间中的全局函数。
• @param：给出变量的简要说明；使用JSDoc @paramsyntax表示细节（例如，如果变量是可选的，则为默认值）。在末尾使用句点。
• @yield：对于生成器函数，此函数预期产生的值的描述。与其他描述一样，在末尾添加一个句点。
• @return：注意描述后的句号。

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @since      x.x.x
 * @deprecated x.x.x Use new_function_name() instead.
 * @access     private
 *
 * @class
 * @augments parent
 * @mixes    mixin
 *
 * @alias    realName
 * @memberof namespace
 *
 * @see  Function/class relied on
 * @link URL
 * @global
 *
 * @fires   eventName
 * @fires   className#eventName
 * @listens event:eventName
 * @listens className~event:eventName
 *
 * @param {type}   var           Description.
 * @param {type}   [var]         Description of optional variable.
 * @param {type}   [var=default] Description of optional variable with default variable.
 * @param {Object} objectVar     Description.
 * @param {type}   objectVar.key Description of a key in the objectVar parameter.
 *
 * @yield {type} Yielded value description.
 *
 * @return {type} Return value description.
 */

骨干类

Backbone 的extend调用格式如下：

• **@lends**此标记将允许 JSDoc 将 Backbone 中的函数识别extend为类定义。这应该放在包含类定义的对象之前。

Backbone 的initialize函数应该格式化如下：

• 摘要：对函数用途的简短一行解释。在末尾使用句点。
• 描述：对摘要的补充，提供更详细的描述。在末尾使用句号。
• @deprecated x.x.x：仅用于已弃用的类，并提供该类被弃用的版本，该版本应始终为 3 位数字（例如@deprecated 3.6.0），以及要使用的类。
• @since x.x.x: 初始介绍应为 3 位数（例如@since 3.6.0）。如果进行了重大更改，@since则应添加其他标签、版本和描述以作为更改日志。
• @constructs: 将此函数标记为此类的构造函数。
• @augments：列出直接父母。
• @mixes: 列出混入类中的mixins。
• @requires：列出此类需要的模块。@requires可以使用多个标签。
• @alias：如果这个类首先被分配给一个临时变量，这允许您更改它记录下的名称。
• @memberof：如果 JSDoc 无法自动解决这个问题，则此类包含在其中的名称空间。
• @static：对于类，用于标记一个函数是类构造函数上的静态方法。
• @see: 依赖的函数或类。
• @link: 提供更多信息的 URL。
• @fires: 构造函数触发的事件。应该列出类名。
• @param：记录传递给构造函数的参数，即使没有在 中明确列出initialize。在末尾使用句点。
  • 主干模型被传递attributes和options参数。
  • 主干视图传递一个options参数。

Class = Parent.extend( /** @lends namespace.Class.prototype */{
    /**
     * Summary. (use period)
     *
     * Description. (use period)
     *
     * @since      x.x.x
     * @deprecated x.x.x Use new_function_name() instead.
     * @access     private
     *
     * @constructs namespace.Class
     * @augments   Parent
     * @mixes      mixin
     *
     * @alias    realName
     * @memberof namespace
     *
     * @see   Function/class relied on
     * @link  URL
     * @fires Class#eventName
     *
     * @param {Object} attributes     The model's attributes.
     * @param {type}   attributes.key One of the model's attributes.
     * @param {Object} [options]      The model's options.
     * @param {type}   options.key One of the model's options.
     */
    initialize: function() {
        //Do stuff.
    }
} );

如果 Backbone 类没有初始化函数，则应使用@inheritDoc以下方法对其进行记录：

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @since      x.x.x
 * @deprecated x.x.x Use new_function_name() instead.
 * @access     private
 *
 * @constructs namespace.Class
 * @memberOf   namespace
 * @augments   Parent
 * @mixes      mixin
 * @inheritDoc
 *
 * @alias    realName
 * @memberof namespace
 *
 * @see   Function/class relied on
 * @link  URL
 */
Class = Parent.extend( /** @lends namespace.Class.prototype */{
// Functions and properties.
} );

注意：由于 JSDoc 的 inheritDoc 标签存在错误，目前它没有提供预期的功能。请参阅JSDocs3 问题 1012。

局部函数

有时函数会在被分配为类成员之前分配给局部变量。
此类函数应标记为使用它们的命名空间的内部函数~。
函数的格式应如下所示：

/**
 * Function description, you can use any JSDoc here as long as the function remains private.
 *
 * @alias namespace~doStuff
 */
var doStuff = function () {
// Do stuff.
};
Class = Parent.extend( /** @lends namespace.Class.prototype */{
    /**
     * Class description
     *
     * @constructs namespace.Class
     *
     * @borrows namespace~doStuff as prototype.doStuff
     */
    initialize: function() {
    //Do stuff.
    },
    /*
     * This function will automatically have it's documentation copied from above.
     * You should make a comment ( not a DocBlock using /**, instead use /* or // )
     * noting that you're describing this function using @borrows.
     */
    doStuff: doStuff,
} );

命名空间

有时类将具有仅分配给局部变量的祖先。这些类应该分配给它们的子类所在的命名空间，并使用~.

类成员

类成员的格式应如下所示：

• 简短描述：在末尾使用句点。
• @since x.x.x: 初始介绍应为 3 位数（例如@since 3.6.0）。如果进行了重大更改，@since则应添加其他标签、版本和描述以作为更改日志。
• @access：如果成员是私有的、受保护的或公共的。私有成员仅供内部使用。
• @type：列出类成员的类型。
• **@property**列出该对象具有的所有属性，以防它是一个对象。在末尾使用句号。
• @member：可选地使用它来覆盖 JSDoc 的成员检测，而不是@type强制类成员。
• @memberof：可选地使用它来覆盖这是哪个类的成员。

/**
 * Short description. (use period)
 *
 * @since  x.x.x
 * @access (private, protected, or public)
 *
 * @type     {type}
 * @property {type} key Description.
 *
 * @member   {type} realName
 * @memberof className
 */

命名空间

命名空间的格式应如下所示：

• 简短描述：在末尾使用句点。
• @namespace：将此符号标记为名称空间，可选择提供名称作为覆盖。
• @since x.x.x: 初始介绍应为 3 位数（例如@since 3.6.0）。如果进行了重大更改，@since则应添加其他标签、版本和描述以作为更改日志。
• @memberof: 包含此命名空间的命名空间。
• @property：此命名空间公开的属性。在末尾使用句号。

/**
 * Short description. (use period)
 *
 * @namespace realName
 * @memberof  parentNamespace
 *
 * @since x.x.x
 *
 * @property {type} key Description.
 */

行内评论

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

单行注释

// Extract the array values.

多行注释

/*
 * 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 JSDoc wrapping and comment block style.
 */

**重要说明：**多行注释不能以/**（双星号）开头。请改用/*（单个星号）。

文件头

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

只要有可能，所有 WordPress JavaScript 文件都应包含标题块。

WordPress 使用 JSHint 进行一般代码质量测试。任何内联配置选项都应放在标题块的末尾。

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @link   URL
 * @file   This files defines the MyClass class.
 * @author AuthorName.
 * @since  x.x.x
 */
/** jshint {inline configuration here} */

支持的 JSDoc 标签

标签

不支持的 JSDoc 标签

标签