ECMAScript 6文档生成器
我正在寻找EcmaScript 6的文档生成器。我没有find一个。
- JSDoc 3没有支持https://github.com/jsdoc3/jsdoc/issues/555
- Docco没有发现
- SmartComments没有发现，但不太可能，太小的项目
- YuiDoc没有发现
- NaturalDocs没有发现，但没有专注于JavaScript
- SphinxDoc没有find
那么真的没有ES 6的文档生成器了吗？
现在有几个ES6文档生成器。 我目前推荐ESDoc，因为它是目前最完整的文档生成器。
我会根据需要更新。
ESDoc
ESDoc支持JSDoc语法，parsing大部分（或全部）ES6并输出漂亮的HTML文档 。 ESDoc使用esdoc.json文件进行configuration，可以logging整个目录。 它整合了摩卡覆盖生成。 还有一个JSON输出。
Docchi
Docchi只是在一个文件上运行，并输出一个描述JavaScript代码的JSON文件。 它不创build任何HTML或其他呈现的文档，并指出它不符合许多AST节点。 但它使用的是与Dox相同的JSON，因此应该可以使用与Dox相同的查看器。
JSDoc
根据一个Github的问题， JSDoc支持ES6的一部分，但它错过了很多部分，并拒绝整个文件例如出口项目。
转录
转录是试图编写一个ES6文档生成器，但最后一次提交是从2015年3月16日。
YUIDoc
YUIDoc部分支持ES6。
documentationjs
Documentationjs是一个新的文档生成器。 它支持ES6，并允许您以标准的JSDoc格式编写您的文档注释。
我也花时间寻找一个体面的ES6文档生成器，没有发现，所以我开始写我自己的转录 。 它甚至不是很接近正确的testing，但它可以在单个文件上工作，并输出JSON，Markdown和HTML（在这一点上是非风格和非常基本的）。
对于有兴趣做类似事情的人来说， Acorn （代表JavaScript对象代码）和Doctrine （用于处理注释块和doclet）是一对库，可以帮助你。
如果你想看看它对样本class级产生了什么，这应该让你开始：
-
git clone https://github.com/affirmix/transcription.git -
cd transcription -
npm install -
gulp - 以下命令之一:(分别用于JSON，Markdown和HTML）
-
node dist/app.js ./input -f json -o ./output.json -
node dist/app.js ./input -f md -o ./output -
node dist/app.js ./input -f html -t ./jade -o ./output
-
如果构build工具是一个选项，我会把源代码es6转换器（巴贝尔），然后pipe道结果到jsdoc发电机。 因此，任何es6语法都可以在不等待原生JSDOC支持的情况下得到支持。
这是一个使用node.js和gulp的例子：
var gulp = require('gulp'); var babel = require('gulp-babel'); var jsdoc = require('gulp-jsdoc'); gulp.task('jsdoc', function() { return gulp.src('**/*.js') .pipe(babel()) .pipe(jsdoc.parser()) .pipe(jsdoc.generator('./docs')); });
这里是webapplate项目的工作源代码
你可以告诉JSDoc忽略不是/**注释的东西，防止它抛出parsing错误。
这意味着JSDoc不会尝试对代码做任何解释，但是我发现你需要对JSDoc注释非常详细。 这是一个使用node.js和gulp的例子：
var gulp = require('gulp'); var jsdoc = require('gulp-jsdoc'); gulp.task('jsdoc', function() { return gulp.src('./client/**.js') .pipe(jsdoc.parser({plugins: ['plugins/commentsOnly']})) .pipe(jsdoc.generator('./doc')); }); gulp.task('default', ['jsdoc']);
这不是一个完美的解决scheme，但它可以让你有ESD代码的JavaDoc风格的文档，而不必跳过篮球。
注 ： commentsOnly插件中存在一个已知的错误，导致它不从包含零注释的文件中移除代码。 我提交了一个pull请求，它已经在最新版本的JSDoc中修复了，但是gulp-jsdoc并没有更新它的依赖关系，并且在不久的将来可能不会。
要解决这个问题，要么确保每个文件至less有一个/**注释，要么手动修补插件。 该插件可以在node_modules/gulp-jsdoc/node_modules/jsdoc/plugins/commentsOnly.js 。 这个：
if (comments) { e.source = comments.join('\n\n'); }
应该：
if (comments) { e.source = comments.join('\n\n'); } else { e.source = ''; // If file has no comments, parser should still receive no code }
似乎已经支持了几个星期的类语法现在https://github.com/jsdoc3/jsdoc/issues/555#issuecomment-83232420 （安装主https://github.com/jsdoc3/jsdoc的说明; ） – 我会给它去一个报告（整个事情似乎在节点的ES6parsing能力的枢纽）。
我推荐jsdoc3（usejsdoc.org），主要是因为它似乎是在IDE中进行JavaScripttypes检查和自动完成的“事实上的”标准，比如visual studio code，webstorm，netbeans，eclipse等。总的来说，你可以获得大部分好处types化的语言，如打字稿或stream，但100％的香草JavaScript。 在IDE中进行types检查也是使代码和jsdoc同步的理想select。
顺便说一下，我是https://github.com/cancerberoSgx/short-jsdoc的作者，因为我不喜欢任何当前解决scheme的语法，所以它定义了一个更小的/直观的/简单的语法，并增加了大量缺less的function。; 但在大型/公共项目/ API中，我使用jsdoc3的原因如上所述。
