文档注释生成库调研

发表于 | 更新于: | 分类于 ， | 阅读次数:
字数统计: 2,455 | 阅读时长 ≈ 9

为mediasoup准备，或者其他后来的可能性；接触了好些文档了
仍然没有使用经验；不过，md经验不少，除了没有写过一些公式/流程图等

2018.2.22 四 17:10

A [Javascript自动化文档工具：YUI Doc, JSDoc 3, JSDuck等比较]

jsduck yuidoc jsdoc-3 文档生成 javascript yeelan0319 2015年03月05日发布
https://segmentfault.com/a/1190000002579067

文中涉及的工具

JSDoc 3、YUIDoc、Dox、Docco、JSDuck

比较标准

  • 生成文档的易读性
  • 工具的可扩展性
  • 注释语法标准
  • 注释语义的丰富程度

长话短说

对没有兴趣了解细节比较的你，可以快速浏览下面的总结来了解这些工具。

  1. YUIDoc是YUI的附属项目。YUI团队希望这个文档工具不仅仅可以支持Javascript，而是更多的脚本语言，因此它并不考虑实际的代码实施细节，而只是对注释部分进行了扫描。从好的一面来说，如果你同时使用了Ruby/PHP/Python等等，YUI或许是一个比较适合的工具。从反面来说，因为它没有考虑实施细节，你需要额外的变量声明、同时生成的文档有可能会和实际的实施细节不吻合。

  2. JSDoc 3的前身是JSDoc Toolkit。它会对代码的具体实施进行扫描，因此你如果不按照符合JSDoc的注释语法来进行注释的话，可能生成的文档一个字也没有。虽然它的学习曲线很高，但是一旦掌握了之后，由于它提供了完整的模版开发，事件触发等等接口，其灵活性也是不容小觑的。

  3. Dox是一个非常轻量级和可以定制化的工具，它使用和JSDoc 3兼容的注释语法标准，并将其转化成JSON格式。因此在呈现方式上具有比JSDoc 3更强的可定制性，当然也意味着你初期的麻烦会比较多。

  4. Docco是一种行间注释的方式。比起API注释，它更适合于注释代码的实施逻辑，以便于后期程序员能够快速捕捉到原作者在此处的实施意图。应该说是非常适合开源项目、多个作者共同维护的一个文档工具。比如最经典的Backbone Annotated Source就是使用Docco进行注释的。

  5. JSDuck由Sencha开发，因此对于自家extJS具有非常强大的支持功能，包括令人咋舌的实时代码修改。但即使你不是使用extJS进行开发，JSDuck仍然是一个非常强大的工具，一方面它的语法非常灵活，描述支持Markdown语法，上手难度远远低于JSDoc 3；另一方面它生成的文档可读性堪比YUIDoc，同时支持源码的对照，学习起来也非常的容易。要说JSDuck有什么不好的地方，估计就是它把一切都Handle太完美了以致于没有给你提供什么可以自己定制的余地。

最后我选择了JSDuck作为文档生成的工具。从目的上说，我需要生成的是提供给Q&A和其他团队成员参考的API文档，考虑到毕竟写代码才是我们的主要工作，注释和文档越简单能够表达意思越好用，而JSDuck恰好十分符合我的需求。但是你选择使用哪种工具还需要根据使用场景来具体考虑，还请参考下面的细节比较

细节比较（JSDoc 3, YUI, JSDuck）

1 生成文档的易读性（YUIDoc、JSDuck）

。。。

# B [给 Web 开发人员推荐的文档生成工具]
阅读 1492 收藏 112 2017-09-22 原文链接：my.oschina.net
https://juejin.im/entry/59c47ad7f265da065e323334

C 告别手写 API文档生成工具推荐

http://www.csdn.net/article/2013-02-20/2814189-API_DOC_TOOLS
发表于2013-02-20 10:19| 次阅读| 来源CSDN| 0 条评论| 作者张红月
APIAPI文档工具开放平台

摘要：随着API的迅速发展，如何编写出更加规范的API文档说明则显的尤为重要。你是否还通过手写的方式来生成和编写这些文档呢？那么你就OUT啦！话说工欲善其事必先利其器，本文分享8款非常好的API文档生成工具给大家。

随着API的发展以及需求的日益增加，对API文本文档的需求与随之而来。相信许多开发人员都遇到过编写API文档方面的问题及烦恼。
你是否还通过手写的方式来生成和编写这些文档呢？那么你就OUT啦！话说工欲善其事必先利其器，本文分享8款非常好的API文档生成工具给大家。

Web API文档工具列表

  1. Swagger ——Swagger框架可以通过代码生成漂亮的在线API，甚至可以提供运行示例。支持Scala、Java、Javascript、Ruby、PHP甚至 Actionscript 3。在线 Demo 。

  2. I/O Docs ——I/O Docs是一个用于RESTful Web APIs的交互式文档系统。使用 JSON 模型根据资源、方法和参数定义 APIs。I/O Docs 将生成 JavaScript 客户端接口，可通过这些接口来调用系统。服务器端基于 Node.js 开发。在线Demo

  3. apiary.io ——能够快速启动和运行文档，包括GitHub集成和I/O验证——更多建议可以前往Reddit查看上关于 Siyfion讨论。

  4. Docco ——Docco是一个快速而随意、hundred-line-long、迭代程序风格的文档生成器。它会以HTML的方式显示评论和代码。

  5. Dexy ——非常灵活的一款文档工具，支持任何语言编写的API。

  6. Doxygen ——Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。对于未归档的源文件，也可以通过配置Doxygen来提取代码结构。 更多建议可以前往Reddi上查看 gkumar007相关讨论。

  7. TurnAPI ——是一款付费的文档API工具。里面包含了智能WIKI编辑器、基于标准的Markdown、文档分支、还可以与Git、SVN、Mercurial同步、整洁的主题、友好的界面。

以上仅是作者在实践中发现的一些很好的工具，如果你有更好的建议或工具推荐，欢迎与我们分享。
来自：MATTSILVERMAN

# D JavaScript 文档生成工具
2014-01-22 JavaScript
http://blog.inching.org/JavaScript/2014-01-22-javascript-document.html

=================
# E 利用 Gitbook 生成文档中心站点
2016-02-17
http://blog.bugtags.com/2016/02/17/gitbook-docs/

====================
# F [JSDoc中文文档]
http://www.css88.com/doc/jsdoc/index.html
## 使用Markdown插件

# G APIDOC
http://apidocjs.com/

# H 使用Swagger构建Node.js API文档与Mock Server
Erum 关注 2017.10.27 17:52* 字数 1257 阅读 282评论 0喜欢 0赞赏 2
https://www.jianshu.com/p/50446a0513f8

# I dox, 使用 Markdown 和jsdoc的节点的JavaScript文档生成器
https://www.helplib.com/GitHub/article_58201

==============================
# A Documentation generator for JS client? #2079
https://github.com/swagger-api/swagger-codegen/issues/2079
# B swagger-api/swagger-js
https://github.com/swagger-api/swagger-js
Javascript library to connect to swagger-enabled APIs via browser or nodejs http://swagger.io
# C Surnet/swagger-jsdoc
https://github.com/Surnet/swagger-jsdoc
Generates swagger doc based on JSDoc.
# D wisdomtool/rest-client
https://github.com/wisdomtool/rest-client
A tool for automated testing REST API, generating exquisite testing report and REST API documentation.
# E JacksonTian/doxmate
https://github.com/JacksonTian/doxmate
文档伴侣 http://html5ify.com/doxmate

============================

Z 实际

一 资料整理

  1. 就前三篇分析比较，文档生成工具
  2. 第五篇 是利用 Gitbook生成文档中心站点：和文档还有点不同，取可取
  3. F和G 是jsdoc第三方文档，官网
  4. H是swagger的应用，和工作文档同（restfull api）
  5. 后面基本都是一些工具类
  6. C 可以写swagger注释，生产swagger的风格
  7. D 估计是利用swagger生成的产品
  8. 最后 Doxmate，风格不错，有模板

好像还有esdoc

二 选择

2.1 分析

  1. JSDoc 3还不错，虽然样式丑，但自主开发性高，已有一些不错的模板，而且见到几个文档也是JSDoc，比如video.js,debugger.js等npm包
  2. 上述基本都是基于前端的，生成md文件，然后可以再用插件生成网站；对前端友好
    而非，swagger的json，yaml格式。
  3. 实际有swagger和php生成的restful api，样式做restful api还不错
  4. swagger好像比JSDOC等文档注释要丰富一点，
    好在，swagger有插件可以写基于JSDOC注释，写swagger风格样式
  5. 文档注释，JSDOC适中一点，没有swagger复杂，也不那么随意
  6. JSDOC的文档相对其他几个好一些（swagger文档也不错）
  7. 基于前端的几个，Dox可以使用和JSDoc 3兼容的注释语法标准，并将其转化成JSON格式（考虑可以向swagger转）
    E doxmate差不多就是dox

2.2 结果

从分析，可知识JSDoc（名字上也和JS有联系，天生的喜感；用的也多，简单，稳定，可扩展）

18:10

三 补充

  1. 上述是从代码文件中，提取注释，生成md或者静态html文件，从而生成文档API网页
  2. swagger是json或者YAML格式的文件，生成文档API网页；也可以从代码注释中提取
    单独的JSDOc 不知道不能生成文档文件
  3. 也可以直接写md文件，生成文档API，可以利用gitbook等其他方式生成网站。（hexo搭建的博客系统，也可以生成网页）
  4. 也可以直接写html等格式文件，自定义样式
  5. restfullAPI，php中应用的swagger注释，可提取出json或YAML格式文件产生网页；
    该网页可交互：用户提交（符合格式的）请求，可以返回相应的结果
knowledge is no pay,reward is kindness
分享到： 收藏夹 复制网址 邮件 微信 QQ空间 腾讯微博 豆瓣 一键分享 更多
0%