jsdoc to markdown

原文：https://www.npmjs.com/package/jsdoc-to-markdown

markdown API文档生成器

本文档是一个工作正在进行中

jsdoc在文档的源代码输入，markdown 格式的API文档输出。

概要

写文件的代码：

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

运行命令：

$ jsdoc2md example/src/protection.js

得到 markdown 的文档！ （用github-flavored-markdown 默认格式）

<a name="protection"></a>
## protection(cloak, dagger) ⇒ <code>survival</code>
a quite wonderful function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | <code>object</code> | privacy gown |
| dagger | <code>object</code> | security     |

这个命令可以实现相同的结果：

$ jsdoc-parse example/function.js | dmd

特征

• 将API机制的文档插入一个README，或任意文件。
• 自定义一个规则水平。如果输出不适合你，改变它。
• 打包您的修改，发布到NPM并与他人分享（如dmd-bitbucket）
• accepts.js或.html输入文件（解析HTML是实验性的 - 更多）
• 扩展了jsdoc用一些新的标签（更多）
• 使用任意标记，例如@fulfil，@reject，@hatredlevel等。

示例输出

一些示例输出创建使用jsdoc2md。

生成的自述文件

这些项目中插入jsdoc2md输出到readme模板。

项目	笔记
handbrake-js	模块露出两个方法和一个内部类。 API文档插入readme模板通过此命令：$ jsdoc2md –template jsdoc2md/README.hbs lib/*.js
array-tools	很简单的模块输出的静态方法的集合。演示使用@typicalname的（设定为a）和@Category标签组标识符在成员列表中。
ansi-escape-sequences	演示使用@enum{类型}（以表格形式呈现）。
file-set	简单的模块导出类。

标签

你可以看到对每一jsdoc标记看起来当呈现在这里时的一个例子。

实例演示各种选项
为了得到一个想法的影响的各种选项有：

• 格式化选项
  
  • example-lang
  • module-index-format
  • global-index-format
  • member-index-format
  • param-list-format
  • property-list-format
  • no-gfm
  • separators
  • name format
• 解析选项
  
  • html
  • sort-by

脚本示例

如果你使用命令行工具不能实现你所需要的，你可以写一个自定义脚本。

• 生成 markdown 文件每一个类

模板实例

默认jsdoc2md输出可能并不总是适合你。您可以使用自己的模板,使用该模板选项。你可以看到用来生成这个readme的模板。

选择器

• Cherry-pick 其中文档出现输出使用选择助手。
  
  • {{#module}}
  • {{#class}}

安装和使用

首先，您的源代码文档使用正确的jsdoc语法，然后通过jsdoc-to-markdown 使用以下方法（在Mac OSX，Linux和windows8.1和Windows XP的所有测试）：

命令行工具

要全局安装jsdoc2md命令行工具，运行：

$ npm install -g jsdoc-to-markdown

一些典型使用案例：

$ # dump everything you have into a single file 
$ jsdoc2md "src/**/*.js" > api.md

$ # split into separate files 
$ jsdoc2md src/main-module.js > main-module.md
$ jsdoc2md src/important-class.js > important-class.md

$ # embed documentation into a template you made 
$ jsdoc2md "src/**/*.js" --template readme.hbs > README.md

注意在通配

一般规则：如果你的文件表达式中包含* * 递归尚未失败，用引号括起表达式（例如”lib/* * / *.js”）。

如果用引号包裹，bash（或你的shell）不会试图文件名扩展在表达式上。如果不使用引号，你将需要bash的版本4+与globstar启用递归工作。

添加“生成文档”任务到你的项目工作流程

作为npm的运行任务
这是最轻量级的方式添加任务 - 不需要额外任务运行的软件。第一：

$ npm install jsdoc-to-markdown --save-dev

随后，package.json的“scripts”一节中，添加一个文档的任务。 例如：

{
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

现在，项目文档，像这样产生的：

$ npm run docs

作为一个grunt任务
看 grunt-jsdoc-to-markdown.

作为一个gulp任务
看 gulp-jsdoc-to-markdown.

贡献
问题报告和补丁的鼓励。而该项目将受益于额外的维护..

组成
从本质上讲，jsdoc2d连接jsdoc-parse的输出到DMD的输入。 DMD使用DDATA辅助库（也由DHTML共享）和数据流以产生输出。

API参考

例子

var jsdoc2md = require("jsdoc-to-markdown");

jsdoc2md([options]) ⇒ TransformStream ⏏
变换jsdoc到markdown的文档。

kind:导出的函数
params

• [options] DmdOptions | ParseOptions - the options

例子

两种方法来使用jsdoc2md。无论是传递文件路径（**全局匹配支持）JavaScript源文件：

> jsdoc2md({ src: "lib/*.js" }).pipe(process.stdout);

或管道中的源代码来自其他资源：

fs.createReadStream("lib/main.js").pipe(jsdoc2md()).pipe(process.stdout);

dmd~DmdOptions

所有DMD选项及其缺省值

kind:DMD的内部类

• ~DmdOptions
  
  • .template : string
  • .heading-depth : number
  • .example-lang : string
  • .plugin : array
  • .helper : array
  • .partial : array
  • .name-format : string
  • .no-gfm : boolean
  • .separators : boolean
  • .module-index-format : string
  • .global-index-format : string
  • .param-list-format : string
  • .property-list-format : string
  • .member-index-format : string
  • .group-by : array

dmdOptions.template : string

该模板所提供的文档会被渲染成。使用默认或提供自己的模板完全控制的输出。

kind:DmdOptions的实例属性
default:”{{>main}}”

例子

var fs = require("fs");
var dmd = require("../");

var template = "The description from my class: {{#class name='MyClass'}}{{description}}{{/class}}";

fs.createReadStream(__dirname + "/my-class.json")
    .pipe(dmd({ template: template }))
    .pipe(process.stdout);

输出：

The description from my class: MyClass is full of wonder

使用命令行工具的equivation操作：

$ dmd --template template.hbs --src my-class.json

dmdOptions.heading-depth : number

最初的标题深度。例如，具有值2的顶层markdown标题看起来像“##的标题”。

kind:DmdOptions的实例属性
default:2

dmdOptions.example-lang : string

指定使用@example块（语法高亮显示的目的）的默认语言。在GFM模式下，每个@example被包裹在一个 fenced-code块。用法示例：–example-lang js。使用特殊值none因为没有特定的语言。在使用这个选项，你可以覆盖语言提供任何@example通过指定@lang子标签，如@example @lang hbs。指定@example @lang off将禁用代码块的例子。

kind:DmdOptions的实例属性
default:”js”

dmdOptions.plugin : array

使用含有帮助 和/或 部分覆盖安装的软件包

kind:DmdOptions的实例属性

dmdOptions.helper : array

处理帮助程序文件来覆盖或继承默认设置
kind:DmdOptions的实例属性

dmdOptions.partial : array

处理部分文件覆盖或继承默认设置
kind:DmdOptions的实例属性

dmdOptions.name-format : string

在代码样式格式标识符名称，（即使用反引号格式的或）
kind:DmdOptions的实例属性

dmdOptions.no-gfm : boolean

默认情况下，DMD产生github-flavoured的markdown。并非所有的markdown解析器正确地呈现GFM。如果您生成的文档看起来不正确的网站上比其他Github上（如npmjs.org）尝试启用这个选项来禁用Github-specific 的语法。

kind:DmdOptions的实例属性

dmdOptions.separators : boolean

把

---

放在标识符之间。提高了笨重文档的可读性。

kind:DmdOptions的实例属性
default:false

dmdOptions.module-index-format : string

none, grouped, table, dl

Kind: DmdOptions的实例属性
Default: “dl”

dmdOptions.global-index-format : string

none, grouped, table, dl
Kind: DmdOptions的实例属性
Default: “dl”

dmdOptions.param-list-format : string

两个选项渲染参数列表：’list’或’table’（默认值）。表格式适用于大多数情况下，但切换到列表中，如果事情开始变得拥挤/压扁。

Kind: DmdOptions的实例属性
Default: “table”

dmdOptions.property-list-format : string

list, table

Kind: DmdOptions的实例属性
Default: “table”

dmdOptions.member-index-format : string

grouped, list

Kind: DmdOptions的实例属性
Default: “grouped”

dmdOptions.group-by : array

域的列表，以组成员索引

Kind: DmdOptions的实例属性
Default: [“scope”,”category”]

jsdocParse~ParseOptions
所有jsdoc-parse选项，其中包括默认

kind:jsdocParse 的内部类

• 解析选项
  
  • .src : string | Array.
  • .private : boolean
  • .stats : boolean
  • .html : boolean
  • .sort-by : array

parseOptions.src : string | Array.

源文件进行解析。如果没有设置这个选项jsdoc-parse会等待输入到流式传输。

kind:ParseOptions的实例属性
例子

var parse = require("jsdoc-parse");
var fs = require("fs");

// either supply one or more file names 
parse({ src: "example.js" }).pipe(process.stdout);

// or pipe in source code 
fs.createReadStream("example.js").parse().pipe(process.stdout);

parseOptions.private : boolean

包括标识符文档标记为@private在输出

Kind: ParseOptions的实例属性
Default: false

parseOptions.stats : boolean
打印有关doclet解析的数统计
Kind: ParseOptions的实例属性

parseOptions.html : boolean

启用的.html文件的实验分析。

Kind: ParseOptions的实例属性
Default: false

parseOptions.sort-by : array
排序通过其中一个字段，例如 –sort-by kind 类别。

Kind: ParseOptions的实例属性
Default: [“scope”,”category”,”kind”,”order”]