你认为什么是优秀的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跳转到文档.

• 格式良好,您希望复制和粘贴的代码片段(如方法签名)脱颖而出.

• 从文档链接到带有示例代码的项目.

• 自动文档刷新机制,但默认情况下,文档都是本地启动(因此您可以使用片状互联网连接).

• 轻松地在文档变体之间切换(查看不同版本的操作系统),还可以选择要运行搜索的文档集.

• 概述部分解释了该类的用途,后面是分解按目的分组的方法的部分(创建和对象的方法,查询数据的方法,使用类型转换的方法等),然后是详细的方法说明.

我个人也非常喜欢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

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

例如:http: //www.php.net/manual/en/function.fopen.php

我认为有效的文件包括:

• 参数列表
• (有用)参数的描述
• 如果它们的参数是一个字符串,请列出并解析每个可能的参数
• 返回成功执行和不成功执行的值
• 它可能引发的任何异常/错误
• 示例(最重要的是imo)

可选:

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

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

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

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

Answer 6

这是一些非常糟糕的文档:Databinder Dispatch.Dispatch是一个用于HTTP的Scala库,它抽象出(Java)Apache Commons HTTP库.

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

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

回答这个问题:"我怎么用Y做X？" 你可能知道答案.我不.