JSDoc中文文档(@use JSDoc)

关于JSDoc插件

目录

创建并启用插件

创建并启用新JSDoc插件,需要两个步骤：

  1. 创建一个包含你的插件代码的JavaScript模块.
  2. 将该模块添加到JSDoc配置文件的plugins数组中。你可以指定一个绝对或相对路径。如果使用相对路径，JSDoc按照相对于配置文件所在的目录，当前的工作目录和JSDoc安装目录的顺序搜索插件。

例如，如果你的插件是在当前工作目录下，plugins/shout.js文件中定义的，你应该在JSDoc配置文件中的plugins数组中添加字符串plugins/shout。

示例: 在JSDoc配置文件中添加一个插件：
{
    "plugins": ["plugins/shout"]
}

JSDoc按配置文件plugins数组中列出的顺序执行的插件。

创建JSDoc3插件

JSDoc 3的插件系统广泛的控制着解析过程。一个插件可以通过执行以下任何一项操作，影响解析结果：

事件处理程序

最高级别，一个插件可以注册具体命名事件的处理程序，让JSDoc触发。 JSDoc将一个事件对象传递给处理程序。你的插件模块要导出一个包含处理程序的handlers对象，像这样:

示例: 事件处理程序插件 'newDoclet' 事件：
exports.handlers = {
    newDoclet: function(e) {
        // Do something when we see a new doclet
    }
};

JSDoc触发事件的顺序和底层代码是一样。

事件处理程序插件可以通过设置事件对象的stopPropagation属性(e.stopPropagation = true)停止运行后面的插件。一个插件可以通过设置preventDefault属性（e.preventDefault = true）阻止触发事件。

事件: parseBegin

JSDoc开始加载和解析源文件之前，parseBegin事件被触发。你的插件可以通过修改事件的内容，来控制哪些文件将被JSDoc解析。

注意：此事件在JSDoc3.2及更高版本有效。

该事件对象包含下列属性：

事件: fileBegin

当解析器即将解析一个文件fileBegin事件触发。如果需要，你的插件可以使用此事件触发每个文件的初始化。

该事件对象包含下列属性：

事件: beforeParse

beforeParse事件在解析开始之前被触发。插件可以使用此方法来修改将被解析的源代码。例如，你的插件可以添加一个JSDoc注释，也可以删除不是有效JavaScript的预处理标记。

该事件对象包含下列属性：

下面是为一个函数增加了一个虚拟的doclet到源文件的例子，这样它会被解析并添加到文档。这样做，文档的方法就可以提供给用户，但在被文档化的源代码中不可能出现，如由外部超类所提供的方法：

exports.handlers = {
    beforeParse: function(e) {
        var extraDoc = [
            '/**',
            ' * Function provided by a superclass.',
            ' * @name superFunc',
            ' * @memberof ui.mywidget',
            ' * @function',
            ' */'
        ];
        e.source += extraDoc.join('\n');
    }
};

事件: jsdocCommentFound

每当JSDoc注释被发现,jsdocCommentFound事件就会被触发。注释可以或不与任何代码相关联。您可以在注释被处理之前使用此事件修改注释的内容。

该事件对象包含下列属性：

事件: symbolFound

当解析器在代码中遇到一个可能需要被文档化的标识符时，symbolFound 事件就会被触发。例如，解析器会为源文件中每个变量，函数和对象字面量触发一个symbolFound事件。

该事件对象包含下列属性：

事件: newDoclet

newDoclet事件是最高级别的事件。新的doclet已被创建时，它就会被触发。这意味着一个JSDoc注释或标识符已被处理，并且实际传递给模板的doclet已被创建。

该事件对象包含下列属性：

所述的doclet的属性取决于doclet表示的注释或标识符。你可能会看到一些共同的属性包括：

To see the doclets that JSDoc generates for your code, run JSDoc with the -X command-line option.

下面是一个newDoclet 处理程序的一个例子说明：

exports.handlers = {
    newDoclet: function(e) {
        // e.doclet will refer to the newly created doclet
        // you can read and modify properties of that doclet if you wish
        if (typeof e.doclet.description === 'string') {
            e.doclet.description = e.doclet.description.toUpperCase();
        }
    }
};

事件: fileComplete

T当解析器解析完一个文件时，fileComplete 事件就会被触发。你的插件可以使用这个事件来触发每个文件的清理。

该事件对象包含下列属性：

事件: parseComplete

JSDoc解析所有指定的源文件之后，parseComplete事件就会被触发

注意: 此事件在JSDoc3.2及更高版本会被触发。

该事件对象包含下列属性：

事件: processingComplete

JSDoc更新反映继承和借来的标识符的解析结果后，processingComplete事件被触发。

注意: 此事件在JSDoc3.2.1及更高版本中会被触发。

该事件对象包含下列属性：

标签定义(Tag Definitions)

添加标签到标签字典是影响文档生成的一个中级方式。在一个newDoclet事件被触发前，JSDoc注释块被解析以确定可能存在的说明和任何JSDoc标签。当一个标签被发现，如果它已在标签字典被定义，它就会被赋予一个修改doclet的机会。

插件可以通过导出一个defineTags函数来定义标签。该函数将传递一个可用于定义标签的字典，像这样：

exports.defineTags = function(dictionary) {
    // define tags here
};

字典(The Dictionary)

字典提供了以下方法：

A tag's onTagged callback can modify the contents of the doclet or tag.

示例: Defining an onTagged callback
dictionary.defineTag('instance', {
    onTagged: function(doclet, tag) {
        doclet.scope = "instance";
    }
});

The defineTag method returns a Tag object, which has a synonym method that can be used to declare a synonym for the tag.

示例: Defining a tag synonym
dictionary.defineTag('exception', { /* options for exception tag */ })
    .synonym('throws');

Node Visitors

At the lowest level, plugin authors can process each node in the abstract syntax tree (AST) by defining a node visitor that will visit each node. By using a node-visitor plugin, you can modify comments and trigger parser events for any arbitrary piece of code.

Plugins can define a node visitor by exporting an astNodeVisitor object that contains a visitNode function, like so:

示例: Example
exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // do all sorts of crazy things here
    }
};

The function is called on each node with the following parameters:

Making things happen

The primary reasons to implement a node visitor are to be able to document things that aren't normally documented (like function calls that create classes) or to auto generate documentation for code that isn't documented. For instance, a plugin might look for calls to a _trigger method since it knows that means an event is fired and then generate documentation for the event.

To make things happen, the visitNode function should modify properties of the event parameter. In general the goal is to construct a comment and then get an event to fire. After the parser lets all of the node visitors have a look at the node, it looks to see if the event object has a comment property and an event property. If it has both, the event named in the event property is fired. The event is usually symbolFound or jsdocCommentFound, but theoretically, a plugin could define its own events and handle them.

As with event-handler plugins, a node-visitor plugin can stop later plugins from running by setting a stopPropagation property on the event object (e.stopPropagation = true). A plugin can stop the event from firing by setting a preventDefault property (e.preventDefault = true).

Reporting Errors

If your plugin needs to report an error, use one of the following methods in the jsdoc/util/logger module:

Using these methods creates a better user experience than simply throwing an error.

Note: Do not use the jsdoc/util/error module to report errors. This module is deprecated and will be removed in a future version of JSDoc.

示例: Reporting a non-fatal error
var logger = require('jsdoc/util/logger');

exports.handlers = {
    newDoclet: function(e) {
        // Your code here.

        if (somethingBadHappened) {
            logger.error('Oh, no, something bad happened!');
        }
    }
};