javascript - 如何为文档化的 JavaScript 函数轻松创建 Github 友好的降价？

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) {
     ...

并有一些简单的方法来产生漂亮的降价：

##`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”是可以访问该函数的命名空间。或者，如果它是匿名函数或私有函数（出于某种原因应该在公共文档中，这是否有意义？？），使用其他约定来表示。也许

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

它不必完全是那种格式，只要在 Github 上看起来不错并且有意义即可。理想的工具应该足够聪明，能够接受像Mustache.js这样的代码并产生良好的输出。如果它可以处理大量源文件并生成一个文档作为输出，或者根据配置生成一组链接的文档，那就更好了。

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

哦，还有一匹小马。

现有选项

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

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

即使我可以得到我想要的 JSDoc 输出，我也需要从 HTML 转换为 markdown。我似乎无法找到一个好的工具，是否存在？

文档

我在 Docdown 上玩了一点，但事实上它是 PHP 对我来说是一种行不通的...

YUIDoc，加上转换

我实际上没有玩过 YUIDoc，但它看起来还不错。不过，我需要一个转换器。它是否容易处理模块并避免显式提供函数名称和导出名称？

Dox和 markdown 模板

Dox 会生成 JSON 作为其输出，因此您需要将其与一些好的降价模板结合起来，并包含一个模板引擎来生成文档。有没有人以有用的方式整理了一组这样的模板？

jGrouse , 加转换

与 ANT 一起运行。下一个...

脚本文档...

这还存在吗？似乎是 Aptana 工作室的一部分，所以这将是一个初学者...... Aptana 似乎没有任何关于它的信息。但是 ScriptDoc.org 有一些关于破解的有趣信息，如果这有帮助的话......

博士后

Pdoc 是基于 Ruby 的，但该工具链并不少见，所以这不是一个大问题。您可以提供自己的模板，所以也许已经有一些很好的降价模板。我没玩过……值得吗？那里有好的降价模板吗？

还有什么？

做你自己的！

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

所以.....

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

score 24 · Accepted Answer

我使用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：

score 7 · Accepted Answer

7

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

于 2013-05-09T16:06:27.573 回答

score 3 · Accepted Answer

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

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

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

score 2 · Accepted Answer

好的。在与自己深思熟虑之后，我会选择 DOX + Underscore/Whatever JS 模板引擎而不是 Node。

应该很简单。您甚至可以插入 Grunt 或类似软件，并让它在监视任务下运行。

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

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

score 1 · Accepted Answer

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

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

score 0 · Accepted Answer

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

但是如果你需要生成多页目录，或者创建自定义助手等，动词也有高级功能。

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

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