我们来聊聊 JavaScript 自动生成文档工具的现状。

JSDoc 3

南

doxdox

石板

hm-doc

荣誉提名

接下来呢？

手写完近千行文档后，我发誓再也不干这种事了。于是，我开始寻找各种能帮我完成这项繁琐工作的最佳工具。

这些工具肯定已经存在了吧？npm install弄点东西，运行个命令，就搞定了，对吧？也许并非如此……

我正在尝试记录函数式 JavaScript 代码，但它似乎比预想的要复杂得多。随着函数式 JavaScript 的兴起，我惊讶地发现它竟然如此复杂。

我只想为类似这样的内容创建文档：

// how do I document you, little function?
const add = x => y => x + y

我希望 VSCODE 的智能感知功能能够理解文档，并且能够生成 Markdown 文件或 HTML 文件。

JSDoc 3

首先，JSDoc 显然是最佳选择。我认为他们在这个领域处于领先地位。但作为一个专注于文档的网站，他们自己的文档却糟糕透顶。我完全找不到任何关于如何正确编写函数add文档的信息。

我发现了一个未解决的问题：支持柯里化函数，并查看了日期。2016 年 10 月。

好吧……JSDoc 安息吧。

南

这正是我想要的。截图看起来很棒，但是……糟糕。JSDoc 版本只有 3。而且该项目上次更新时间是 2017 年 4 月 18 日。

南安息。

doxdox

看起来没问题。上次提交是在 2018 年 2 月 19 日。时间虽然还算久，但不到一年。

所以我联系了他们，询问如何记录柯里化函数？

无线电静默

doxdox 安息。

石板

这是我最喜欢的截图。主题很棒，而且仓库最近也很活跃。

但我该如何使用它呢？乍一看，网站上的文档似乎很全面，但我该如何编写文档呢？

我好像创建了一个 Markdown 文件，然后 HTML 代码就是从这个 Markdown 生成的。我应该把 Markdown 文件放在哪里？Markdown 文件应该叫什么名字？我只能把它用于vagrant文档吗？

我先把这件事搁置一下。

hm-doc

功能：根据 JavaScript 代码中的Hindley-Milner单行 // 注释和可选的 /* */ 块注释生成简单的 Markdown 文档。

这看起来很有意思。柯里化代码的 Markdown 生成器。

VSCODE 可能理解不了太多东西，但至少我可以把我的 API 文档写好。

虽然只给了6星，但我还是打算试试。我已经提交了一个问题。

荣誉提名

ESDoc - 与 JSDoc 类似。

YUIDoc - 类似于 JSDoc。

自动文档- 在 JavaScript 函数上方的注释中编写测试。

React Styleguidist - 一个带有动态样式指南的独立 React 组件开发环境

Storybook - 交互式 UI 组件开发与测试：React、React Native、Vue、Angular

接下来呢？

说实话，我对这些解决方案都不满意，我几乎就要自己开发一个解决方案了。

您使用哪些解决方案来生成代码文档？效果如何？

我的文章大量运用了函数式 JavaScript，如果您需要更多相关内容，请在这里或 Twitter 上关注我@joelnet！

更多文章
让我们一起打造一个 DEV.to 命令行界面……
问我一些关于函数式编程的傻问题