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

Posted 2023-03-28

【中文标题】如何为文档化的 JavaScript 函数轻松创建 Github 友好的降价？

【英文标题】：How to easily create Github friendly markdown for documented JavaScript functions?

【发布时间】：2013-03-19 14:59:30

【问题描述】：

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

/**
 *  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 -> 降价转换

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

即使我可以得到我想要的 JSDoc 输出，我也需要从 HTML 转换为 markdown。我似乎找不到一个好的工具，有吗？

Docdown

我在 Docdown 上玩了一下，但它是 php 的事实对我来说有点不合适...

YUIDoc，加转换

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

Dox，加上markdown模板

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

jGrouse，加转化

与 ANT 一起运行。接下来...

脚本文档...

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

Pdoc

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

还有什么？

还有什么？

自己制作！

在用 JSDoc 搞砸了几个小时试图让它按我想要的方式运行之后，我放弃了 wrote my own quick and dirty solution in Java CharFunk，这是我一直在研究的一个 unicode JavaScript 库。虽然它还没有接近通用用途，但它足以满足我的需要。

---

所以.....

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

【问题讨论】：

虽然我很确定这会因为目前的原因而关闭 - 我喜欢 DOX 和 YUIDoc - 拥有获取 JSON 的能力是非常巨大的。 JSDoc，至少在其当前版本中有点麻烦，所有模板和尴尬的自定义标签创建/使用。

你试过github.com/75lb/jsdoc-to-markdown吗？

那你最后选择了什么？

【参考方案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渲染的自述文件：

handbrake-js array-tools command-line-args

【讨论】：

迄今为止我发现的最好的，但是当我使用 angular *.component.ts 文件时它不起作用。 JSDOC_ERROR: There are no input files to process.;

@JoeyGough 读到：usejsdoc.org/…。您需要在 jsdoc 配置中指定输入文件，然后将配置文件路径传递给 jsdoc2md -c

在使用 JSDoc 和 jsdoc-to-markdown 时如何记录回调参数的类型和名称？

【参考方案2】：

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

【参考方案3】：

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

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

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

【讨论】：

看起来 Mox 不再积极开发 (last commit April 2014)。

@DanDascalescu 它可能仍然有效。不是所有东西都需要永远开发！ :)

【参考方案4】：

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

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

据我回忆，Dox 是相对轻量级的，并且有一个 npm 包 (IIRC)。

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

【讨论】：

同意切换到YUI生成MD。 Dox 还没有完全成熟。内联链接 @link 被忽略，而且，如果编写源文档时牢记 jsDoc 降价解析器，那么 Dox 输出就会出错。它将描述中的每个换行视为输出的新行。

【参考方案5】：

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

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

【参考方案6】：

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

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

关于 API 文档，请参阅使用来自 index.js 的代码 cmets 生成的 example readme。单击标题，它们也是自动生成的。使用 this built-in helper 从指定的任何文件路径生成 API 文档。您还可以使用 glob 模式从多个文件中提取文档。

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

【讨论】：

Verb 是否在源代码中查看类似 JsDoc 的 cmets 以输出 doc？因为那是（如果你读了我的问题，很清楚）我在追求什么

是的。请参阅使用来自index.js 的代码 cmets 生成的 example readme。单击标题，它们也是自动生成的。使用 this built-in helper 从指定的任何文件路径生成 API 文档。您还可以使用 glob 模式从多个文件中提取文档。 Verb 将在没有任何配置的情况下构建 .verb.md。但如果你需要更多，你可以使用verbfile.js