像API文档一样生成jQuery（不是源代码！）

Question

我目前正在为jQuery编写一个插件 现在我想知道我应该如何创建这个插件的文档，因为我猜有比直接编写HTML更好的方法。

但是，我不想将我的文档放入源代码中，从而在调试时找不到正确的行。因此，我正在寻找一种分离文档和源代码的方法。

如何生成jQuery文档？在查看jQuery源代码时，我没有找到任何文档注释，这使我希望我可以使用与他们相同的系统。
他们使用的工具是否以某种方式记录？

我在寻找答案http://api.jquery.com/api/时找到了以下XML文件，这个答案似乎是在jQuery的“build”-process中生成的。 我很乐意将我的文档写入类似的文件，并在其上运行一些工具来“美化”它以便将其显示给用户。

如何为jQuery库创建文档（除了将其放入源代码中）？ 有谁知道jQuery团队使用的工具（或者至少是文档最初的格式）？

非常感谢提前！

Answer 1

看起来NaturalDocs提供了external files（以及源代码）中的文档。

Prototype团队用于记录Prototype PDoc的工具纯粹来自于评论。 （链接已经死了，所以我删除了它。）所以你可以拥有.js文件纯粹是你插件的PDoc评论。 2015：就我而言可以说，PDoc已经死了。

我主张在源代码中提出的评论 - 经典维护问题将它们分开 - 但如果你不这样做，公平的'nuff，这两者似乎都是你的选择。

Answer 2

虽然我不同意在源代码中添加文档可能会使调试期间找到正确的行更加困难，但我很欣赏某些样式的文档可能会冗长而且在尝试“进入代码。“

我非常喜欢他们的'注释源'文档中的underscore.js和backbone.js背后的人采取的方法。

例如，请查看underscore annotated source here。此文档是基于内嵌注释生成的，如source on GitHub中所示。但请注意，这不是繁重的多行文档风格，而是简洁而简洁。我意识到您要求提供文档外文档，但我将此作为您问题的潜在解决方案提交给您。

您可以使用Docco生成此类文档，其中还包含指向Ruby，Python甚至shell脚本实现的链接。

Answer 3

你看过jsdoc吗？

  

JsDoc Toolkit是一个应用程序，   用JavaScript编写，用于   自动生成   模板格式的多页HTML   （或XML，JSON或任何其他   来自基于文本的文档   评论了JavaScript源代码。