你认为什么是优秀的API文档？

Question

我一直都喜欢Java API的文档，但我知道有些人认为它们缺乏。所以我想知道，您认为API文档的一个很好的例子是什么？

请在任何答案中包含链接或实际示例。我希望有一些参考资料，我（以及其他人）当然可以用来改进我们自己的文件。

Answer 1

一份好的文件必须有：

• 数据类型规范 - 通常比实际功能更重要。不要轻易对待。
• 功能规格（这很明显）。包括赋予函数的功能，为什么会这样做（如果不是很明显），以及如果有的则需要注意。
• 将整体绑定到逻辑实体的介绍文档，解释超出实际API代码范围的意图，正确的使用模式和想法。通常，您将获得50种不同的功能，并且您不知道哪些必须使用，哪些不应在特定情况之外使用，建议使用更加模糊的替代方案以及为什么必须使用它们方式。
• 例子。有时他们比其他所有人都重要

我知道如何在GTK +中绘制任意颜色的任意形状。我仍然不知道为什么改变绘图颜色需要三行很长的非常模糊，非常不直观的代码行。记住SVGAlib的setcolorRGB(r,g,b); draw(x1,y1,x2,y2);我发现很难理解GTK +的作者所拥有的东西让事情变得如此复杂。也许如果他们解释了基本概念而不仅仅是记录使用它们的函数，我会理解......

另一个例子：昨天我得到了一个让我理解SQLite的答案。我理解从列中提取数据的函数返回signed long long。我知道整数列可以是1,2,4,6和8字节长。我知道我可以将列定义为“UNSIGNED INT8”或“TINYINT”。我没有得到“亲和力”的意思，我只知道两者都具有“INTEGER”的亲和力。我花了几个小时来寻找时间戳应该是UNSIGNED INTEGER还是INT8，INT8是8位还是8位，以及那个深奥的6字节int的名称是什么？

我错过的是“UNSIGNED INT8”，“TINYINT”等都是“INTEGER”类型的句法糖同义词（总是signed long long），给出的长度用于内部磁盘存储只有，自动和透明地调整以适应最少位数的任何值，并且在API方面完全不可见且无法访问。

Answer 2

实际上iPhone（真的是Mac Cocoa / framework）文档已经相当不错了。我喜欢的功能是：

• 很容易从API中跳转到文档。

• 格式良好且代码片段 你想要复制和粘贴 （如方法签名）脱颖而出。

• 使用示例代码链接到项目 来自文档。

• 自动文档刷新机制， 但默认情况下，docs都是本地的 开始（所以你可以忍受片状 互联网连接）。

• 在变体之间切换的简便方法 文件（看到不同的 版本的操作系统），也可以选择 要运行哪些文档集 搜索。

• 概述部分解释了什么 class是for，后面是section 突破分组的方法 目的（创造和创造的方法） 对象，查询数据的方法， 使用类型的方法 转换等），然后是 详细的方法解释。

我个人也非常喜欢Javadoc和Java系统文档（我用了很多年），我发现有一个好处就是为你自己的类制作自己的自定义文档更容易一些文档。 XCode还允许您使用Doxygen为您自己的类生成文档，但是它需要更多的工作来格式化它以及系统类文档，部分原因是系统框架文档应用了更多的格式。

Answer 3

一个好的API将具有以下特征：

• 易于学习
• 易于使用，即使没有文档
• 难以滥用
• 易于阅读和维护使用它的代码
• 足以满足要求的强大功能
• 易于扩展
• 适合观众

我在API设计中看到的最常见的错误是，当开发人员认为自动生成的XML注释已足够时，然后在基于XML注释自动生成其API之前。这就是我所说的：

///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... } 

如上所述的API只会适得其反，并且会使使用API​​的开发人员感到沮丧。良好的API文档应该为开发人员提供关于如何使用API​​的提示，并让他们深入了解他们原本不会注意到的API的某些方面。

Answer 4

我的主要标准是 - 告诉我我需要知道的一切以及我想知道的一切。

QT有相当不错的文档： http://doc.qt.digia.com/4.5/index.html

Win32 MSDN也很不错，虽然它没有老化。

java文档对我来说太可怕了。他们经常告诉我我不想知道的一切，而不是我想知道什么。 .NET文档也有类似的趋势，尽管那里的问题主要是极端的罗嗦，溢出了这么多多余的细节以及那么多该死的页面。为什么我不能在同一页面中看到类的摘要和方法？

Answer 5

以下是一些非常糟糕的文档：Databinder Dispatch。 Dispatch是一个用于HTTP的Scala库，它抽象出（Java）Apache Commons HTTP库。

它使用了很多功能语法魔法，并不是每个人都会非常清楚，但没有提供明确的解释，也没有提供背后的设计决策。 Scaladocs没用，因为它不是传统的Java风格的库。要真正理解发生了什么，你基本上必须阅读源代码，你必须阅读大量的博客文章和示例。

文档成功地使我感到愚蠢和低劣，并且肯定没有成功帮助我做我需要做的事情。另一方面是我在Ruby社区中看到的大部分文档 - 包括RDoc和FAQs / website / etc.不要只做Javadoc - 你需要提供更全面的文档。

回答这个问题：“我怎么用Y做X？”你可能知道答案。我没有。

Answer 6

我个人认为，良好文档的完美示例是PHP的文档：

举个例子： http://www.php.net/manual/en/function.fopen.php

我认为有效的文件包括：

• 参数列表
• （有用）参数说明
• 如果他们的参数是字符串，列表 尽可能地解决和解释 可能的参数
• 两次成功都返回值 执行和不成功 执行
• 可能引发的任何异常/错误
• 示例（最重要的是imo）

任选地：

• 更新日志
• 其他用户的注释/示例

每当我在PHP文档中查找某些内容时，我几乎都知道如何使用它而无需在互联网上搜索“更好”的示例。通常我需要搜索互联网的唯一时间是我需要找到如何将一组功能用于特定目的。否则，我认为PHP文档是优秀文档的最佳示例。

Python的一个例子是一个好的文档： http://docs.python.org/py3k/library/array.html

它列出了方法，但它没有很好地实际解释它是什么，以及如何使用它。特别是当你将它与PHP文档进行比较时。

Answer 7

我喜欢Twitter's documentation。对我来说，一个好的API是最新的，易于阅读并包含示例。

Answer 8

基本上，在班级讲述班级的故事。这是为什么？它该怎么办？这应该是什么？是谁写的？

讲述方法级别的方法故事。这是做什么的？无论你的方法名称有多准确，20-30个字符都不会总是为了描述而削减它。

@author：

• 是谁写的？谁为此感到自豪？谁应该为自己的工作感到羞耻？

接口级文档告诉我：

• 这应该怎么做？
• 它将返回什么？

实施级别文档告诉我：

• 它是怎么做到的？什么样的算法？什么样的系统负载？
• 什么条件可能会导致问题？将null输入导致问题？是负数还好吗？

班级文件告诉我：

• 这里有什么？我应该找到什么样的方法？
• 这个班级代表什么？

@Deprecated告诉我：

• 为什么要计划拆除？
• 什么时候会被删除？
• 建议更换什么？

如果某些事情是最终的：

• 你为什么不让我延长这个？

如果某些东西是静止的：

• 在班级级别的doc中提醒我，至少是含蓄的。

一般情况下：您正在为下一位开发人员编写这些内容，以便在您点击彩票时使用。你不想为退出和购买游艇感到内疚，所以要注意清晰度，不要以为你是为自己写作。

作为附带好处，当有人要求您在两年后使用相同的代码工作并且您已经忘记了所有相关内容时，您将从良好的代码内文档大量受益。

Answer 9

只是一些想法......

1. 示例 - win32 API文档优于iPhone，因为：

   • （简短）代码示例
     
     

   我投票支持任何带有小型和有意义的示例的API文档

2. 永远不要在屏幕截图或示例代码中显示“Form1”，“asdf”，“测试用户”

   • 良好的API解决了现实世界的问题，应该有一些有意义的例子
     
     

3. 不要自动生成文档

   • 文档不应该在编写代码期间（或由同一个人）完成
   • doc适用于程序员通常不关心的陌生人
     
     

4. 避免使用___V2版本的API

   • 但这不是文档问题

Answer 10

我认为一个好的API文档需要清楚地解释：

1. 此API解决了什么问题
2. 何时使用
3. 何时不使用
4. 显示API“最佳实践”用法的实际代码

不完整的API文档但是非常有用的是Oracle数据库文档，例如：为the SELECT statement。我喜欢包含有助于澄清用法的图表。

Answer 11

良好的文档至少应包含以下内容：

• 当一个参数有超出其类型的附加限制时，需要完全指定它们。
• 调用方法之前对象的[required]状态的描述。
• 调用方法后对象状态的描述。
• 方法提供的错误信息的完整描述（返回值，可能的例外）。简单地命名它们不可接受。
  • Good example：如果index小于0，则抛出ArgumentOutOfRangeException - 或者index大于或等于Count。
  • 错误示例：成功返回0或以下E_INVALIDARG等之一...（未指定使参数无效的内容）。这是PS3 SDK中采用的标准“FU开发人员”方法。

此外，以下内容非常有用：

• 如果方法抛出异常，则描述对象的状态。
• 关于API中的类和类组（例如.NET中的exceptions）的最佳实践。
• 使用示例。

基于此：

• 精彩文档的一个示例是MSDN库。
  • 公平地说，在线版本确实存在导航困难的情况。
• 可怕的文档的一个示例是PS3 SDK。学习API需要对方法参数进行大量测试，以猜测任何给定方法的实际要求和行为可能是也可能不是。

Answer 12

IMO 示例是最好的文档。

Answer 13

优秀的API文档的第一点是API本身的良好命名。方法和参数的名称应该全部说明。如果所讨论的语言是静态类型的，则使用枚举而不是String-或int-constants作为参数，以在一组有限的选项之间进行选择。现在可以在参数类型中看到哪些选项可用。

文档的“软部分”（文本，而不是代码）应该包括边界情况（如果我将null作为参数会发生什么），并且该类的文档应该包含一个用法示例。

Answer 14

我非常喜欢Qt4 Documentation，它首先只会向您提供使您工作所需的基本信息，如果您想深入挖掘，它会揭示子章节中的所有血腥细节。

我真正喜欢的是，他们将整个文档构建到Qt Creator中，它可以在您需要时提供上下文相关的帮助和简短示例。

Answer 15

我最近遇到过this文档（Lift JSON的库），这似乎是许多人要求的一个很好的例子：好的概述，好的例子，用例，意图等。

Answer 16

我一直希望在文档中看到一件事：每个函数或类的“基本原理”段落。为什么这个功能在那里？它是为什么建造的？它提供了什么，不能以任何其他方式实现？如果答案是“没有”（并且经常出现这种情况），那么它是什么简写，为什么这个东西足够重要，以便拥有自己的功能？

本段应易于编写 - 如果不是，则可能是可疑界面的标志。

Answer 17

我发现的最佳文档是Python。您可以使用sphinx将源文档生成为HTML，LaTeX等，还可以从源文件生成文档;您正在寻找的API文档。

API文档不仅是最终文档的质量，而且还是开发人员和/或技术作者实际编写文档的容易程度，因此选择一种工具可以使工作更轻松。

Answer 18

转到Doxygen站点并查看它生成的HTML示例。这些都很好：

http://www.doxygen.nl/results.html

Answer 19

许多实际的，现实世界的例子是必须的。最近jQuery的API documentation的重写是一个很好的例子，以及Django的传奇文档。

Answer 20

关于良好文档的大部分内容已经被提及，但我认为缺乏一些关于JavaDoc API文档方法的方面：可以轻松区分所有不同类和接口的使用场景，尤其是区分应该由库客户端使用的类和不应该使用的类之间。

通常，JavaDoc几乎就是你得到的，通常没有包文档页面。然后会遇到一个数百甚至更多类的列表：在哪里以及如何开始？使用该库的典型方法是什么？

如果有一些惯例可以很容易地将这些信息作为JavaDoc的一部分提供，那将会很好。然后生成的API文档可以为不同的人群提供不同的视图 - 至少有两组：实现库的人和使用它的人。

Answer 21

我发现Google APIs是Good documentation API的一个很好的例子。

他们有：

1. 鸟瞰整个API结构
2. 单一API的主要功能概述
3. 快速反馈的精美彩色示例
4. 详细参考
5. 让您了解更新的博客
6. 记录问题和解决方案的google groups
7. 画
8. 常见问题
9. 文章
10. 演示
11. Code Playground
12. 在一堆文档中爬行的搜索引擎

就是这样！ 当我使用谷歌API文档网站时，我有宾至如归的感觉。

Answer 22

文档只是API设计的一部分。有人可能会说后者比命名要重要得多。想想有意义的非重复方法名称等。

我肯定会建议观看Josh Bloch的演讲： http://www.infoq.com/presentations/effective-api-design或http://www.youtube.com/watch?v=aAb7hSCtvGw

这不仅包括您正在寻找的内容，还包括更多内容。

Answer 23

文档质量的唯一标准是它加速了开发。如果您需要知道某些内容是如何工作的，那么您可以阅读文档。如果您从第一个文档比第二个文档更快地理解所有内容，那么一个文档比另一个文档更好。

任何其他品质都是主观的。风格，交叉引用，描述......我知道喜欢看书的人。书风格的doc（带内容/索引/等）对他有好处。另一个我的朋友喜欢在代码中记录所有内容。当他下载新图书馆时，他会获取资源并“读取”它们而不是文档。

我个人而言，就像JavaDocs一样。例如，除了较低级别的部分之外的Apple dev文档，Obj-C运行时（参考部分）被描述得非常糟糕。一些网站API也有我喜欢的文档。

不喜欢MSDN（一般来说它很好但是同一文档的变体太多，我经常迷路）。

Answer 24

大多数人都列出了构成良好API文档的要点，因此我不打算重复这些（数据类型规范，示例等）。我将提供一个示例，我认为它说明了应该如何完成：

Unity Application Block（转到CHM的下载部分）

参与这个项目的所有人都做了很好的记录，以及如何使用它。除了API参考和详细的方法描述外，还有很多文章和样本可以为您提供全局，原因和方法。拥有如此优秀文档的项目很少见，至少是我使用和了解的项目。

Answer 25

我喜欢我的文档，在顶部有一个简短的概述，下面有完整的功能示例，以及这些下的讨论！令我惊讶的是，很少有包含简单函数参数及其所需的变量类型和默认值，特别是在php！

中

我恐怕我不能真正举一个例子，因为我没有去寻找我最喜欢的那些，但是我知道这可能不算数，因为它非官方但是Kohana 3.0's Unofficial Wiki By Kerkness才是辉煌的！并且Kohana 2.34 documentation也很好地布局，至少对我而言。你们觉得怎么样？