生成类似于jQuery的API文档（不是从源代码生成！）

Question

生成类似于jQuery的API文档（不是从源代码生成！）

4

我目前正在编写一个jQuery插件。
现在我想知道该如何为此插件创建文档，因为我猜测直接编写HTML并不是最好的方式。
但是，我不想把文档放入源代码中，这样会使调试时查找正确行变得困难。因此，我正在寻找一种将文档和源代码分离的方法。
jQuery文档是如何生成的？当查看jQuery源代码时，我没有找到任何文档注释，这让我希望我能够使用与他们相同的系统。
他们使用的工具是否有文档说明？
我在寻找答案时找到了以下XML文件http://api.jquery.com/api/ ，它似乎是在"构建"jQuery过程中某个时刻生成的。
我很高兴将我的文档编写到类似的文件中，并运行一些工具将其"美化"以向用户显示。
你是如何为jQuery库创建文档的（除了将其放入源代码中）？
有人知道jQuery团队使用的工具吗（或者至少知道文档最初的格式是什么）？
非常感谢！

- Matthias

8

“然而，我不想将我的文档放入源代码中，因为这会使得在调试时查找正确代码行变得不可能。” - T.J. Crowder

3

完全同意@T.J.的观点，添加注释到JS源代码中绝不会使"在调试时找到正确的行"变得更加困难。 - Matt Ball

我已经遇到了在没有文档的情况下导航文件的问题。我的插件还远未完成，代码行数超过1000行。在C＃/Java中，我会将其拆分为多个文件并将文档添加到源代码中。然而，在JavaScript中这不是一个选项。而且这不仅仅是在调试时：当阅读代码时，我认为文档注释只会分散注意力，让人无法专注于实际代码。 - Matthias

@Matt Ball：没有重复；链接问题的已接受解决方案指向一个“扫描您的代码并从中构建高质量HTML文档”的工具。 <-- 这不是我想要的。 - Matthias

3

@winSharp93：与在调试中找到正确行的困难程度“不可能”相去甚远。；-) 任何像大多数现代浏览器内置的良好调试器都将使它几乎不可能不这样做，因为它可以在逐步模式下突出显示当前行。对于仅有1,000行代码，我并没有看到问题，我发现编程编辑器的搜索功能完全能够胜任。同意这不是重复问题，尽管看起来NaturalDocs（那里的被接受答案）可能为您提供了一个外部文件的解决方案。 - T.J. Crowder

显示剩余2条评论

3个回答

1

虽然我不同意在源代码中添加文档会使调试时更难找到正确的行，但我赞赏某些文档风格可能会冗长且在尝试“进入代码”时有点让人不舒服的情感。

我真的很喜欢underscore.js和backbone.js背后的人们采取的方法，在他们的“注释源”文档中。

例如，请查看这里的underscore注释源。此文档是基于内联注释生成的，如在GitHub上的源代码中所示。但请注意，这不是重型、多行文档风格，偏爱冗长而不是简洁。我知道你要求文件外的文档，但我向你提交这个作为你问题的潜在解决方案。

您可以使用Docco生成此类文档，它还包括到Ruby、Python甚至shell脚本实现的链接。

- Matt

虽然不是我正在寻找的，但对于代码示例肯定很有用。谢谢 - 我不会在这个问题上使用它，但在其他时候可能会用到。 - Matthias

-1

你有研究过jsdoc吗？

JsDoc Toolkit是一款JavaScript应用程序，可以自动生成基于模板的、多页HTML（或XML、JSON或任何其他文本格式）文档，从JavaScript源代码中获取注释。

- herostwist

1

从已注释的 JavaScript 源代码中生成文档。 - Matthias

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- T.J. Crowder · Accepted Answer

看起来 NaturalDocs 不仅可以在源代码中提供文档，还可以在外部文件中提供文档。

Prototype 团队用于记录 Prototype 的工具 PDoc 仅从注释中提取信息。（该链接已失效，因此我将其删除。）因此，您可以拥有纯粹是插件的 PDoc 注释的 .js 文件。2015 年：据我所知，PDoc 已经停止更新。 我建议将注释放在源代码中，以便更好地维护，但如果您不想这样做，那么以上两种方法似乎都可行。