jsdoc使用markdown插件

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

概览

JSDoc包括markdown插件，自动把Markdown-formatted文本转换成HTML。你可以使用这个插件与任何JSDoc模板。在JSDoc3.2.2及以后，降价插件使用了明显的markdown解析器。

注意：当您启用markdown插件，一定要包括在您的JSDoc注释的每行起始的星号。如果省略前导星号，JSDoc的解析器可能会删除星号,用于markdown格式化。

默认情况下，JSDoc查找markdown格式的文本在以下JSDoc标签：

• @author
• @classdesc
• @description (包括未标记描述在一个JSDoc注释的开始)
  
  • @param
  • @property
  • @returns
  • @see
  • @throws

启用markdown插件

要启用markdown插件，添加字符串plugins/markdown到插件数组，在您的JSDoc配置文件中：

配置文件，使用markdown插件

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

转换markdown用额外的JSDoc标签

默认情况下，markdown插件只处理特定的JSDoc标签为markdown文本。您可以通过添加一个markdown.tags属性设置为您JSDoc配置文件来处理的其他标记markdown文本。该markdown.tags属性包含额外的doclet属性，可以包含markdown文本数组。 （在大多数情况下，doclet属性的名称相同的标签名。然而，一些标签存储方式不一样;例如，@param 标签存储在的doclet的params属性。如果你不知道如何标签的文本存储在一个doclet中，运行JSDoc使用-X/–explain，打印每个的doclet到控制台）

例如，如果foo和bar标签接受在一个的doclet的foo和bar的属性中存储值，你可以使用markdown处理这些标签，通过添加下面的设置到您JSDoc配置文件：

转换markdown用’foo’和’bar’标签

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["foo", "bar"]
    }
}

剔除markdown处理的默认标签

为了防止降价插件处理任何默认JSDoc标签，添加一个markdown.excludeTags属性到您的JSDoc配置文件。该markdown.excludeTags属性包含默认标签的数组,不应该对markdown文本处理。

例如，要从markdown处理排除author标签：

剔除markdown处理的“author”标签

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "excludeTags": ["author"]
    }
}