如何轻松创建 Github 友好的 markdown 以记录 JavaScript 功能？

Question

我希望能够在 JavaScript 源代码中的任何地方使用这样的 JSDoc 注释（甚至嵌套在几个函数层中，在一个模块中，甚至是匿名函数中）：

/**
 *  Used to do some important thing that needs doing that works like xyz.
 *  @param {String} whatever - some string that has some purpose
 *  @param {Function} callback - a function that needs to be run
 *  @returns {Boolean} whether or not something happened
 */
 function something(whatever, callback) {
     ...

并有一些简单的方法来生成漂亮的 markdown：

##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.

*Parameters*
  `whatever {String}` some string that has some purpose
  `callback {Function}` a function that needs to be run

*Returns*
   `{Boolean}` whether or not something happened

其中“root”是可以访问 function 的命名空间。 或者，如果它是匿名的 function 或私有的 function（出于某种原因应该在公共 doco 中，这甚至有意义吗？？），请使用其他一些约定来表示它。 可能是

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

它不必完全是那种格式，只要在 Github 上看起来不错并且有意义即可。 理想的工具应该足够智能，能够使用Mustache.js之类的代码并生成良好的 output。如果它可以处理大量源文件并生成一个文档 output 或一组链接的文档，则效果会更好，具体取决于配置。

最好是以一种可以完全轻松地包含在 git 存储库中的方式完成，这样人们就不需要设置高度特定的工具链来更新 doco。 或者至少需要一个最小的工具链。

哦，还有一匹小马。

---

现有选项

JSDoc ，加上某种 HTML -> markdown 转换

JSDoc 非常好。 但我似乎无法让它与模块一起工作。 或者更确切地说，这比恕我直言应该更麻烦。 我不需要添加额外的标签来命名 function。我已经尝试了 @export 和 @name，但仍然无法按照我想要的方式将其显示在最终文档中。 如果有人可以指向一个 JSDoc 注释源，其中包含模块并且做得很好，那可能会有所帮助。 更新： JSDoc v3 实际上似乎比 v2 更适合模块，所以这可能更合适。

即使我可以像我想要的那样获得 JSDoc output，我也需要从 HTML 转换为 markdown。我似乎找不到一个好的工具，是否存在？

文档下载

我玩过 Docdown 但事实上它是 PHP 对我来说有点不可能......

YUIDoc , 加上转换

我实际上还没有玩过 YUIDoc，但它看起来不错。 尽管如此，我还是需要一个转换器。 它是否轻松处理模块并避免必须显式提供 function 名称和导出名称？

Dox ，加上 markdown 模板

Dox 生成 JSON，因为它是 output，因此您需要将其与一些好的 markdown 模板结合，并包括一个模板引擎来生成文档。 有没有人以有用的方式将一组这样的模板放在一起？

jGrouse ，加上转换

使用 ANT 运行。接下来...

脚本文档...

这甚至还存在吗？ 似乎是 Aptana studio 的一部分，所以这将是一个失败者...... Aptana 似乎没有任何关于它的信息。 但是 ScriptDoc.org 有一些关于 crack 的有趣信息，如果有帮助的话......

文档

Pdoc 基于 Ruby，但该工具链并不少见，因此这不是一个大问题。 您可以提供自己的模板，这样也许已经有一些不错的 markdown 模板了。 我没玩过它...它值得吗？ 那里有好的 markdown 模板吗？

还有别的吗？

外面还有什么？

自己做！

在与 JSDoc 搞了几个小时试图让它按照我想要的方式工作之后，我放弃了并在 Java 中为CharFunk 编写了我自己的快速而肮脏的解决方案，这是一个我一直在研究的 unicode JavaScript 库。 虽然它还没有接近通用目的，但它足以满足我的需要。

---

所以.....

这是一个未满足的需求还是只是我？

Answer 1

我用jsdoc-to-markdown ..

写文档代码：

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

得到降价文档：

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

这些项目有jsdoc2md呈现的自述文件：

• 手刹-JS
• 阵列的工具
• 命令行-ARGS

Answer 2

你试过jsdox吗？

它是一个node.js jsdoc到markdown生成器。

Answer 3

markdox可以从javascript代码生成markdown文档。

Answer 4

jsDox。 https://github.com/sutoiku/jsdox使用UglifyJS完整解析

莫克斯。 https://github.com/tjchaplin/mox几个可立即运行的示例/模板。

两者都处理JSDoc / Dox格式。 两者都有积极的发展。 对我来说，Mox因为示例套件而获胜。

Answer 5

好。 经过我自己的一些考虑，我会选择DOX + Underscore / Whatever JS模板引擎。

应该很简单。 你可能甚至可能会遇到Grunt或类似的东西，并让它在监视任务下运行。

据我所知，Dox相对轻巧，并且有一个npm包（IIRC）。

更新：我想，经过一些经验，我想改变我对YUIDoc的回答。

Answer 6

尝试使用动词 。 在最简单的用例中，Verb将使用package.json中的数据从模板构建自述文件。

但是，如果您需要生成多页TOC或创建自定义帮助程序等，动词也具有高级功能。

关于API文档，请参阅此示例使用index.js代码注释生成的自述文件。 点击标题，这些也是自动生成的。 使用此内置帮助程序从指定的任何文件路径生成API文档。 您还可以使用glob模式从多个文件中提取文档。

Verb将在没有任何配置的情况下构建.verb.md 。 但是如果你需要更多，你可以使用verbfile.js

Answer 7

我需要从JSDoc创建一个API文档，它应该易于使用，并且还支持现代前端堆栈。 一些提到的库存在JS代码转换为babeljs的问题，因此您必须暂时使用注释来转换代码以生成降价文档。

对于这样的用例，我发现http://documentation.js.org/非常有用，因为它们集成了对BabelJs配置的支持，因此它负责从JSDocs生成markdown（JSON，HTML）。