你认为什么好的API文档？(What do you consider good API documentation? [closed])

你认为什么好的API文档？(What do you consider good API documentation? [closed])

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

请在任何答案中包含链接或实际示例。 我想提到我（和其他人，当然）可以用来改进我们自己的文档。

I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?

Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.

最满意答案

一个很好的文件必须有：

数据类型规范 - 通常比实际功能更重要。 不要轻易对待。 功能规格（这是很明显的）。 包括什么给定功能，为什么它（如果不明显），以及警告如果有的话。 介绍文档将整体绑定到一个逻辑实体，解释意图，正确的使用模式和超出实际API代码范围的想法。 通常你会得到50个不同的功能，你不知道哪一个必须被使用，哪些不能在特定的情况之外使用，哪些被推荐用于更晦涩的替代品，以及为什么要这样使用它们。 例子。 有时他们比所有其他人更重要

我知道如何在GTK +中绘制任意形状的任意颜色。 X- 记住SVGAlib的setcolorRGB(r,g,b); draw(x1,y1,x2,y2); 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方面是完全不可见和不可访问的。

A good documentation MUST have:

datatypes specs - often more essential than actual functions. Do NOT treat this lightly. function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any. an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way. examples. Sometimes they are more important than all the rest

I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...

Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?

What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.