你认为什么是良好的API文档？
总的来说，我一直很喜欢Java API的文档，但是我知道有些人认为它们缺乏。 所以我想知道，你认为什么是一个API文档的好例子？
请在任何答案中包含一个链接或一个实际的例子。 我想引用我（和其他人）当然可以用来改进我们自己的文档。
一个好的文档必须有：
- 数据types规范 – 通常比实际function更重要。 不要轻视这一点。
- function规格（这是显而易见的）。 包括给定的函数做什么，为什么它（如果不是明显的），和警告（如果有的话）。
- 一个将整体结合成一个逻辑实体的入门文档，解释超出实际API代码范围的意图，正确的使用模式和想法。 通常情况下，你会得到50个不同的function，你不知道哪些是必须使用的，哪些不应该在特定情况下使用，哪些是推荐给更加模糊的select，为什么必须这样使用。
- 例子。 有时他们比其他人更重要
我知道如何在GTK +中绘制任意形状的任意颜色。 我仍然不知道为什么绘画颜色的变化需要三行非常模糊，相当不直观的代码。 记住SVGAlib的setcolorRGB(r,g,b); draw(x1,y1,x2,y2); setcolorRGB(r,g,b); draw(x1,y1,x2,y2); 我发现很难理解GTK +的作者是如何使事情复杂化的。 也许如果他们解释的基本概念，而不是仅仅logging使用它们的函数，我会明白…
另一个例子：昨天我得到了一个让我理解SQLite的答案。 我理解一个函数从列中提取数据返回signed long long 。 我知道整数列可以是1,2,4,6和8字节长。 我明白我可以定义一个列为“UNSIGNED INT8”或“TINYINT”。 我不太清楚“亲和力”是什么意思，我只知道它们都具有“完整”亲和力。 我花了几个小时来查询时间戳应该是UNSIGNED INTEGER还是INT8，INT8是8位还是8字节，这个深奥的6字节int是什么名字？
我所错过的是，“UNSIGNED INT8”，“TINYINT”等都是“INTEGER”types的语法糖同义词（总是标记为signed long long ），给出的长度仅用于内部磁盘存储，自动调整并透明地适应任何价值最less的位数，是完全不可见的，从API方面无法访问。
其实iPhone（Mac Cocoa / framework）文档已经相当不错了。 我喜欢的function是：
-
非常容易从API跳转到文档。
-
很好格式化和代码片段，你想复制和粘贴（如方法签名）脱颖而出。
-
从文档链接到示例代码的项目。
-
自动文档刷新机制，但默认情况下文档都是本地启动（所以你可以住在一个片状的互联网连接）。
-
在文档变体之间切换的简单方法（查看不同版本的操作系统），以及select运行search的文档集合。
-
概述部分解释了类的用途，接下来是按目的分组的方法（用于创build和对象的方法，用于查询数据的方法，用于types转换的方法等），然后是详细的方法说明。
我个人也非常喜欢Javadoc和Java系统文档（我使用了很多年），我发现有一个好处，那就是为自己的类创build自定义的文档，这些文档与系统文档stream畅地交织在一起。 XCode还允许您使用Doxygen为您自己的类生成文档，但需要更多的工作来格式化系统类文档，部分原因是系统框架文档应用了更多的格式。
一个好的API将具有以下特点：
- 简单易学
- 易于使用，即使没有文件
- 很难滥用
- 易于阅读和维护使用它的代码
- 足够强大，以满足要求
- 易于扩展
- 适合观众
我在APIdevise中看到的最常见的错误是，开发人员觉得自动生成的XML注释已经足够，然后再根据XML注释自动生成API。 以下是我正在谈论的内容：
///<summary> /// Performs ObscureFunction to ObscureClass using ObscureArgument ///</summary> void ObscureClass.ObscureFunction(ObscureArgument) { ... }
如上所述的API只会起到反作用，并会使开发人员使用API受挫。 良好的API文档应该给开发人员提示如何使用API，并让他们深入了解他们不会注意到的API的某些方面。
我个人认为，良好的文档的一个完美的例子是PHP的文档：
举个例子： http : //www.php.net/manual/en/function.fopen.php
我认为有效的文件包括：
- 参数列表
- （有用）参数的描述
- 如果他们的参数是一个string，列出并解释每一个可能的参数
- 返回成功执行和不成功执行的值
- 任何可能引发的exception/错误
- 示例（最重要的是imo）
可选：
- 更新日志
- 来自其他用户的注释/示例
每当我在PHP文档中查找一些东西时，我几乎都知道如何使用它，而不必在互联网上find“更好”的例子。 通常我需要search互联网的唯一时间是当我需要find如何使用一组function用于特定目的。 否则，我认为PHP文档是优秀文档的最好例子。
什么是思想是好的文档的一个例子是Python的： http : //docs.python.org/py3k/library/array.html
它列出了这些方法，但在深入解释它是什么以及如何使用它方面做得并不好。 特别是当你比较它的PHP文档。
这里有一些非常糟糕的文档： Databinder Dispatch 。 Dispatch是一个用于HTTP的Scala库，它抽象出（Java）Apache Commons HTTP库。
它使用了很多function语法魔法，这不是每个人都会很清楚的，但没有提供清晰的解释，也没有提供任何背后的devise决定。 Scaladocs没有用，因为它不是传统的Java风格的库。 为了真正理解正在发生的事情，你基本上必须阅读源代码，你必须阅读一些博客文章的例子。
文件成功地让我感到愚蠢和低人一等，并且帮助我做我所需要做的事情一定没有成功。 反面是我在Ruby社区看到的大部分文档 – 包括RDoc和常见问题/网站/等等。 不要只做Javadoc – 你需要提供更全面的文档。
回答这个问题：“我如何用Y做X？” 你可能知道答案。 我不。
我的主要标准是 – 告诉我我需要知道的一切，以及我想知道的一切。
QT有不错的文档： http ：
Win32 MSDN也不错，虽然没有老化。
java文档对我来说太可怕了。 他们不断告诉我所有我不想知道的事情，也不知道我想知道的事情。 .NET文档有类似的倾向，虽然问题大多是极端的罗嗦，溢出了太多多余的细节，还有那么多该死的页面。 为什么我不能在同一页面看到一个类的总结和方法？
我喜欢Twitter的文档 。 对我来说，一个好的API是最新的，易于阅读和包含示例。
我认为一个好的API文档需要清楚地解释：
- 这个API解决了什么问题
- 当你应该使用它
- 当你不应该使用它
- 显示API的“最佳实践”用法的实际代码
不完全API文档，但非常有用的是Oracle数据库文档，例如对于SELECT语句 。 我喜欢列举图表，这有助于澄清用法。
只是一些想法…
-
示例 – win32 API文档比iPhone好，因为：
- （简称）代码示例
我投票任何API文档与小而有意义的例子
-
永远不要在屏幕截图或示例代码中显示“Form1”，“asdf”，“testing用户”
- 好的API是解决现实世界的问题，应该有一些有意义的例子
-
不要自动生成文档
- 在编写代码时（或由同一个人）
- doc是一个陌生人，程序员通常不在乎
-
避免___V2版本的API
- 但这不是一个文档问题
基本上讲讲课堂上的故事。 这是为什么呢？ 它应该做什么？ 这里应该是什么？ 谁写的？
讲述方法层面的方法故事。 这是做什么的？ 无论你的方法名称有多精确，20-30个字符都不会总是为了描述而削减。
@作者：
- 谁写的？ 谁为此感到自豪？ 谁应该为自己的工作感到羞耻？
接口级文档告诉我：
- 这应该怎么办？
- 它会返回什么？
实施级文件告诉我：
- 它是如何做到的？ 什么样的algorithm？ 什么样的系统负载？
- 什么情况可能会导致问题？ 将nullinput引起问题？ 是负数还好吗？
级别的文档告诉我：
- 这里到底是什么？ 我应该期望find什么样的方法？
- 这个class代表什么？
@Deprecated告诉我：
- 为什么这是计划搬迁？
- 预计什么时候被删除？
- 什么是build议更换？
如果有什么是最终的：
- 你为什么不要我延长这个？
如果有事情是静态的：
- 至less隐含地提醒我在课堂上的文档。
一般来说： 如果你打中彩票的时候，你正在为下一个开发者编写这些代码。 你不想因为放弃购买游艇而感到内疚，所以请注意清楚一点，不要以为自己是为自己写的。
作为副作用，当两年后有人要求您使用相同的代码，而您已经忘记了这一切，您将从良好的代码文档中大量获益。
API文档的第一点是API本身的一个很好的命名。 方法和参数的名字应该是全部。 如果所讨论的语言是静态types的，则使用枚举而不是String或int常量作为参数，以在有限的一组选项之间进行select。 现在可以在参数的types中看到哪些选项是可能的。
文档（文本，而不是代码）的“软部分”应该覆盖边界情况（如果我给null作为参数会发生什么情况），并且类的文档应该包含一个用法示例。
良好的文档应该至less有以下几点：
- 当一个参数有其他的限制超出了它的types，他们需要充分的指定。
- 在调用方法之前描述对象的[必需]状态。
- 调用方法后对象状态的描述。
- 该方法提供的错误信息的完整描述（返回值，可能的例外）。 简单地命名它们是不可接受的 。
- 很好的例子 ：如果index小于0，则抛出ArgumentOutOfRangeException – 或 – index大于或等于Count。
- 不好的例子：成功返回0，或者下面的E_INVALIDARG等等之一（没有指定什么使得参数无效）。 这是PS3 SDK中采用的标准“FU开发者”方法。
另外，以下是有用的：
- 如果方法抛出exception，则描述对象的状态。
- API中的类和类的最佳实践（比如.NET中的例外 ）。
- 用法示例
基于此：
- 一个伟大的文档的例子是MSDN库。
- 公平的说，这个在线版本确实遇到了导航困难的情况。
- 可怕的文档的一个例子是PS3 SDK。 学习一个API需要广泛的方法参数testing来猜测什么可能或者可能不是任何给定方法的实际要求和行为。
我真的很喜欢Qt4文档 ，它首先只是为了解决问题所需要的基本信息，如果你想深入挖掘，就会在各个小节中看到所有的细节。
我真正喜欢的是，他们将整个文档构build到Qt Creator中，在需要时提供上下文相关帮助和简短示例。
有一件事我一直想在文档中看到：每个函数或类的“基本原理”段落。 为什么这个function在那里？ 它是为了什么而build的？ 它提供了什么不能以其他方式实现？ 如果答案是“没有”（而且出乎意料地频繁），那么这个答案是什么呢？为什么这个东西有足够的重要性来发挥自己的作用呢？
这段应该很容易写 – 如果不是，这可能是一个可疑界面的标志。
海事组织的例子是最好的文件。
我最近遇到了这个文档（提升JSON的库），这似乎是很多人要求的很好的例子：好的概述，好的例子，用例，意图等等。
转到Doxygen网站，看看它生成的HTML的例子。 那些很好：
我喜欢我的文档在顶部有一个简短的概述，下面有全function的例子，并在这些下面的讨论！ 我很惊讶，很less包括简单的函数参数与他们所需的variablestypes和默认值，特别是在PHP！
恐怕我真的不能举一个例子，因为我没有find我最喜欢的东西，但是我知道这可能不算是因为它的非官方的，但Kohana 3.0非官方维基通过Kerkness只是辉煌！ 而且Kohana 2.34文档也是非常好的，至less对我来说是这样。 你们有什么感想？
大多数人已经列出了构成良好API文档的要点，所以我不打算重复这些（数据types规范，示例等）。 我只是想提供一个我认为应该如何完成的例子：
Unity应用程序块 （转到CHM的下载部分）
参与这个项目的所有人都做了很好的logging和如何使用。 除了API参考和详细的方法描述之外，还有大量的文章和样本给你提供了大图，为什么和如何。 有这么好的文件的项目是罕见的，至less是我使用和了解的。
文档质量的唯一标准是加快开发速度。 如果你需要知道如何工作，你去阅读文档。 如果你从第一篇文档比第二篇更快地理解了所有内容，那么一篇文档比另一篇更好。
其他任何特质都是主观的。 样式，交叉参考，描述…我知道喜欢读书的人。 书风格的文档（内容/索引/等）将对他有好处。 另一个我的朋友喜欢在代码中logging一切。 当他下载新的图书馆，他得到的来源和“读取”他们，而不是文档。
我个人喜欢JavaDocs。 像Apple开发文档一样，下层的部分例外，Obj-C运行时（引用部分）被描述得非常好。 几个网站API也有我喜欢的文档。
不喜欢MSDN（这是一般的好，但有太多的同一文件的变种，我经常迷路）。
文档只是整个APIdevise的一部分。 有人可能会认为后者比命名更重要。 想想有意义的非复制方法名称等
我肯定会推荐观看Josh Bloch的演讲： http ： //www.infoq.com/presentations/effective-api-design或http://www.youtube.com/watch？v = aAb7hSCtvGw
这不仅涵盖你要找的东西，还有更多。
许多实际的，现实的例子是必须的。 最近重写jQuery的API文档就是一个很好的例子，以及Django的传奇文档。
我find的最好的文档是Python 。 您可以使用sphinx将源文档生成为HTML，LaTeX等，也可以从源文件生成文档; 您正在寻找的API文档。
API文档不仅是最终文档的质量，也是开发人员和/或技术作者实际撰写文档的容易程度，因此请select一种工具，使工作更轻松。
关于优秀文档的大部分内容已经被提及，但是我认为JavaDoc API文档的缺乏方面有一个方面：可以很容易区分所有不同类和接口的使用场景，特别是区分不同的类应由图书馆客户使用，不应该使用的。
通常情况下，JavaDoc几乎是你所能得到的，通常没有包文档页面。 然后，一个人遇到一个数百甚至更多的课程清单：在哪里以及如何开始？ 什么是使用图书馆的典型方法？
如果有一些惯例可以很容易地将这些信息作为JavaDoc的一部分来提供，那将是一件好事。 然后，生成的API文档可以为不同的人群提供不同的视图 – 至less有两个组：实施图书馆的人员和使用图书馆的人员。
我发现Google API是一个很好的文档API的例子。
他们有：
- 鸟瞰整个API结构
- 概述了单个API的主要function
- 很好的和有色的例子快速反馈
- 详细参考
- 一个博客，让你更新
- 一个文件问题和解决scheme的谷歌组
- 影片
- 常问问题
- 用品
- 演讲
- 代码游乐场
- search引擎在一堆文档中爬行
而已！ 当我玩google API文档网站时，我感到宾至如归。
