你认为什么是良好的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文档需要清楚地解释:

  1. 这个API解决了什么问题
  2. 当你应该使用它
  3. 当你不应该使用它
  4. 显示API的“最佳实践”用法的实际代码

不完全API文档,但非常有用的是Oracle数据库文档,例如对于SELECT语句 。 我喜欢列举图表,这有助于澄清用法。

只是一些想法…

  1. 示例 – win32 API文档比iPhone好,因为:

    • (简称)代码示例

    我投票任何API文档与小而有意义的例子

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

    • 好的API是解决现实世界的问题,应该有一些有意义的例子
  3. 不要自动生成文档

    • 在编写代码时(或由同一个人)
    • doc是一个陌生人,程序员通常不在乎
  4. 避免___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的例子。 那些很好:

http://www.stack.nl/~dimitri/doxygen/results.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的例子。

他们有:

  1. 鸟瞰整个API结构
  2. 概述了单个API的主要function
  3. 很好的和有色的例子快速反馈
  4. 详细参考
  5. 一个博客,让你更新
  6. 一个文件问题和解决scheme的谷歌组
  7. 影片
  8. 常问问题
  9. 用品
  10. 演讲
  11. 代码游乐场
  12. search引擎在一堆文档中爬行

而已! 当我玩google API文档网站时,我感到宾至如归。