关于JSDoc插件

原文：http://usejsdoc.org/about-plugins.html

创建并启用插件

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

1. 创建包含你的插件代码的JavaScript模块。
2. 包括在JSDoc的配置文件的插件数组模块。你可以指定一个绝对或相对路径。如果使用相对路径，JSDoc会搜索该插件在配置文件所在的目录;当前的工作目录;和JSDoc目录，在该顺序。

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

为JSDoc的配置文件，添加一个插件

{    "plugins": ["plugins/shout"]}

JSDoc按它们列出在配置文件中的顺序执行的插件。

创作JSDoc3插件

JSDoc3的插件系统提供了解析过程广泛的控制。一个插件可以通过执行以下任一项，影响的解析结果：

• 定义事件处理程序
• 定义标签
• 定义访问者对抽象语法树节点

事件处理程序

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

事件处理程序插件“newDoclet”事件

exports.handlers = {    newDoclet: function(e) {        // Do something when we see a new doclet    }};

在Node.js中，JSDoc触发事件在相同顺序的底层代码中。在Mozilla Rhino，JSDoc尽快触发所有jsdocCommentFound事件时一旦它开始解析的文件;所有其他事件被触发以相同的顺序作为底层代码。

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

事件：parseBegin

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

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

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

• sourcefiles：路径数组来自源文件将被解析。

事件：fileBegin

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

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

• filename：文件的名称。

事件：beforeParse

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

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

• filename：文件的名称。
• source：文件的内容。

下面是例子增加了一个虚拟的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

每当jsdocCommentFound事件被触发，无论何时在JSDoc评论中发现的。注释可以或可以不与任何代码相关联。您可以使用此事件来修改注释的内容在被处理之前。

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

• filename:该文件的名称。
• comment：在JSDoc注释的文本。
• lineno: 在其评论中发现的行号。

事件：symbolFound

symbolFound事件被触发，当解析器遇到一个符号在代码中，可能需要记录。例如，解析器触发一个symbolFound事件对于每个变量，函数和对象常量在一个源文件中。

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

• filename：该文件的名称。
• comment：注释的文本与符号相关联，如果任何。
• id:符号的唯一ID。
• lineno:在其上的符号被发现的行号。
• range:在该符号相关联的源文件中，包含第一个和最后一个字符的数字索引的数组。
• astnode：从抽象语法树符号的节点。
• code：有关该代码的详细信息的对象。这个对象通常包含名称，类型和节点属性。对象也可能具有value，paramnames，或funcscope属性取决于符号。

事件：newDoclet

该newDoclet事件是最高级别的事件。它被激活当新的doclet已被创建时。这意味着一个JSDoc注释或符号已被处理，并实际的doclet将被传递给模板创建。

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

• doclet：新的doclet被创建。

所述的doclet的属性可以根据注释或符号的表示的doclet而变化。你可能会看到一些共同的特性包括：

• comment：在JSDoc注释文本，或者符号无证空字符串。
• meta：对象，描述如何的doclet涉及源文件（例如，源文件中的位置）。
• description：被记录的符号的说明。
• kind:被记录符号的种类（例如，类别或功能）。
• name:短名称的符号（例如，myMethod）。
• longname:完全限定名，其中包括的memberof信息（例如，MyClass＃myMethod）。
• memberof：该模块，命名空间或类此符号所属的（例如，MyClass的），或一个空字符串如果符号没有父。
• scope:符号在其父项内的范围（例如，全球，静态，实例或内部）。
• undocumented：设置为true，如果符号没有一个JSDoc注释。
• defaultvalue：默认值的象征。
• type：Object包含关于符号的类型的详细信息。
• params：Object包含参数列表为函数。
• tags：对象包含了JSDoc不识别的标记列表。只有可用当allowUnknownTags设置为true，在JSDoc的配置文件中。

下面是一个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

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

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

• filename: 文件名称.
• source:该文件的内容.

事件：parseComplete

该parseComplete事件JSDoc解析了所有指定的源文件之后触发。

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

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

• sourcefiles:路径数组到源代码文件被解析的。
• doclets：doclet对象的数组。见newDoclet事件，有关每个的doclet可以包含属性的详细信息。注意：这个属性可用在JSDoc3.2.1及更高版本。

事件：processingComplete

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

注意：此事件在JSDoc3.2.1及更高版本触发。

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

• doclets：doclet对象的数组。见newDoclet事件，有关每个的doclet可以包含属性的详细信息。

标记定义

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

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

例子

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

词典

字典提供了以下方法：

• defineTag（title，opts）：用于定义标签。第一个参数是标记的名称（例如，参数或概述）。第二个是一个包含标记选项的对象。可以包括以下任一选项;每个选项的默认值是false：
  
  • canHaveType（布尔）：设置为true，如果标签文本可以包含一个类型的表达式（如 {string} in @param {string} name - Description）。
  • canHaveName（布尔）：设置为true，如果标签文本可以包含一个名称（如 name in @param {string} name - Description）。
  • isNamespace（布尔）：设置为true，如果标签应用于该doclet中的longname为命名空间。例如，@module标签设置这个选项设置为true，并使用标签@module myModuleName results 在longname module：myModuleName。
  • mustHaveValue（布尔）：设置为true，如果该标签必须有一个值（如TheName在@name TheName中）。
  • mustNotHaveDescription（布尔）：设置为true，如果该标签可以有一个值，但不能有描述（如TheDescription在@tag{typeExpr} TheDescription）。
  • mustNotHaveValue（布尔）：设置为true，如果标签不能有一个值。
  • onTagged（function）：回调函数执行时标签被发现。该函数传递两个参数：doclet和标签的对象。
• lookUp（标签名）：通过名称检索标签对象。返回标签的对象，包括它的选项，或假如果标签没有定义。
• isNamespace（标签名）：如果标签被应用到的doclet的longname为命名空间，则返回true。
• normalise（标签名）：返回一个标签的规范名称。例如，所述@const标签是同义词@constant;因此，如果你调用normalise（’const’），它返回的字符串常量。
• normalize（标签名）：同义词normalise。可用在JSDoc3.3.0及更高版本。

标签的onTagged回调可以修改doclet或标记的内容。

定义一个onTagged回调

dictionary.defineTag('instance', {    onTagged: function(doclet, tag) {        doclet.scope = "instance";    }});

该defineTag方法返回一个标签对象，它具有同义词的方法可用于声明同义标签。

定义标签同义词

dictionary.defineTag('exception', { /* options for exception tag */ })    .synonym('throws');

节点访问

在最底层，插件作者可以每一个节点处理抽象语法树（AST），通过定义一个节点访问将会访问的每个节点。通过使用节点访问插件，您可以为任意一段代码，修改注释并触发解析器事件。

插件可以定义节点访问，通过导出astNodeVisitor对象包含visitNode 函数，像这样的：
例子

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

该函数在每个节点的调用，具有以下参数：

• node：AST的节点。 AST节点是JavaScript对象,使用由Mozilla的解析器API定义的格式。您可以使用Esprima的解析器演示，看到AST将被创建对于您的源代码。
• e：事件。如果该节点是一个解析器处理，事件对象将已经被填充，在symbolFound事件上用相同的东西描述。否则，这将是空对象在其上设置各种属性。
• parser：本JSDoc解析器实例。
• currentSourceName：该文件的名称被解析。

如果你在Mozilla Rhino 上运行JSDoc，你也可以导出nodeVisitor对象，包含visitNode的函数。所述visitNode函数接收相同的参数astNodeVisitor对象，但该节点参数是Rhino AST节点，其是Java对象，而不是一个Esprima-style JavaScript对象。Rhino节点访问被弃用JSDoc3.3.0，并支持将在JSDoc的未来版本中删除。

使事情发生

实现节点访问的首要原因是为了能够记录事情，那些不寻常的记录（创建类像函数调用），或者自动生成文档为未记录的代码。例如，一个插件可能看起来调用到_trigger方法，因为它知道这意味着一个事件被触发，然后生成文档因为这个事件。

为了使事情发生了，visitNode函数应该修改事件参数的属性。一般来说，目标是构建一个注释，然后得到一个事件触发。在分析器可以让所有的节点的访问都来看看节点之后，它会查看是否该事件对象有一个注释属性和事件属性。如果两个都有，在事件属性命名的事件被触发。该事件通常symbolFound或jsdocCommentFound，但理论上，一个插件可以定义自己的事件和处理它们。

与事件处理程序的插件，一个节点访问插件可以停止后面的插件，运行通过在事件对象上设置stopPropagation属性（e.stopPropagation=true）。一个插件可以通过设置的preventDefault属性停止事件触发（e.preventDefault=true）。

报告错误

如果你的插件需要报告错误，使用下列方法之一在jsdoc/ util/logger 模块中：

• logger.warn：发出警告给用户，可能出现的问题。
• logger.error：报告错误，从该插件可以恢复。
• logger.fatal：报告错误，应引起JSDoc停止运行。

使用这些方法创建不是简单地抛出一个错误，更好的用户体验。

注：请不要使用jsdoc/ util/error 模块报告错误。该模块使用，将在JSDoc的未来版本中删除。

报告一个非致命错误

var logger = require('jsdoc/util/logger');exports.handlers = {    newDoclet: function(e) {        // Your code here.        if (somethingBadHappened) {            logger.error('Oh, no, something bad happened!');        }    }}