JavaScript 自记录代码 API Docs 工具在哪里？答案

【问题标题】：JavaScript Self-documenting code where's the API Docs tools?JavaScript 自记录代码 API Docs 工具在哪里？
【发布时间】：2011-03-17 17:50:47
【问题描述】：

这两个概念似乎违反直觉。争论的一方面认为 cmets 对可读性造成的损害以及违反 DRY（如果 cmets 甚至保持最新）。但是，掷硬币，有必要为您的代码提供良好的 API 文档，以便其他人可以使用您的库。

我见过的每个工具（JSDoc、PDoc 等）都是为生成 API 文档而设计的，它使用大量空间来提供该文档。我需要提供 API 文档，我不需要将我的一半 LOC 进行特殊格式的注释，以便 JSDoc 可以读取它。

我目前正在考虑使用像Jekyll 这样的基本降价工具并将此文档放在 /doc 文件夹中，将其从我的代码中完全删除。有没有其他人找到对他们有用的解决这个问题的方法？

【问题讨论】：

如果您在构建时使用压缩脚本，您真的不必担心代码中的额外行。
完整确认。如果您想提供高质量的文档，则应保留源代码。在生产中使用压缩文件时（无论如何都应该这样做），cmets 根本不重要。
不担心生产文件，压缩机会删除它。我想要不是 75% 特殊格式的 cmets 的可读文件，以便某些工具可以读取它。
我不能对这个问题给予足够的支持。如果没有特殊格式的 cmets，似乎所有 JS 文档工具都不会做任何有用的事情。而且我同意 OP，我不想用腐烂的 cmets 来破坏我的资源。 JavaScript 的动态特性对于此类工具来说是否太难处理？

【解决方案1】：

Sphinx 是一个适用于多种语言的文档工具，它假定您将主要在外部文件中编写文档。它仍然有一个autodoc 扩展，允许您从代码中的 cmets 中提取文档。

我个人认为将 API 文档放在代码附近会更方便，因为它可以帮助我保持最新状态。此外，处理该代码的其他人将能够在需要时获得文档，而无需浏览外部文件。坦率地说，我认为大多数代码行都是 cmets 并没有什么问题：编辑器通常对 cmets 进行不同的着色，并允许您根据需要忽略它们。

【讨论】：