2

我正在制作一个库来生成一些自定义内容。它非常冗长，大约 1100 行代码。尽管代码非常易读并且遵循严格的命名约定，但我不确定在包含脚本文件时在哪里记录可用的 API。在页面中包含脚本时，intellisense 不会选择“公共”方法，jQuery 也不会。jQuery 为其 API 提供了一个很棒的网站（http://api.jquery.com/），但我不觉得做这么棒的东西。

我应该在哪里记录这个自定义 API？

如果在评论中，你会建议什么样的评论结构？

编辑

我对智能感知的观点是，即使是好的命名约定也需要文档化的 API。所以我绝对对通用方法感兴趣。

4

3 回答 3

2

我认为 jsdoc 很受欢迎。

http://code.google.com/p/jsdoc-toolkit/

您将按照链接上的约定进行内联文档。您将分发一个用于部署的缩小/混淆的生产构建，以及用于开发的文档化构建（即您可以这样做）

编辑，您还可以在这里找到更多选项：http: //o2js.com/2011/05/01/how-to-document-a-javascript-framework/

于 2012-05-15T23:03:26.833 回答
1

这取决于您的 api 有多复杂，对于我自己的小型库，我只是在包含

  • 快速记录这一切
  • 如果库对 html 标记进行操作，则可以复制和粘贴一些示例代码
  • 函数列表及其参数和每个函数的单行文档
  • 通常如何使用该库的示例
  • 注释/警告/限制。总有一些奇怪的事情发生，人们不会想到

基本上这就是你放在 C 头文件中的内容。

我想你可以在一个单独的文件中完成我上面提到的所有事情，然后使用 markdown 语法（我太懒了......我更喜欢将所有内容都放在一个文件中）。

ps 有些人提到内联注释（即直接在函数所在的位置）。这当然也是一种选择。但对我来说，这似乎只有在自动生成文档时才方便，这是一种快速研究文件内文档的可怕方式，因为它缺乏大图视图。

于 2012-05-15T23:06:57.640 回答
1

它不是通用的，但如果您不介意为不同的编辑器维护单独的版本，Visual Studio 的 IntelliSense 将在您的 JavaScript 代码中加载和解析 XML 注释。我想 MonoDevelop 和 SharpDevelop 也可以使用相同的文件，但我认为 IntelliJ 或 Eclipse 之类的 IDE 不会从中得到任何用处......

HTH。

于 2012-05-15T23:10:47.990 回答