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

问题描述

我一直很喜欢上的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.

推荐答案

一个良好的文档必须有：

A good documentation MUST have:

• 数据类型规格 - 往往比实际的作用更重要。不要掉以轻心。


• 功能规格（这是显而易见的）。包括哪些特定的功能是，它为什么它（如果不是很明显），并警告如果有的话。


• 整个结合成一个逻辑实体，说明意图，正确的使用模式和理念超越实际的API code范围的介绍文档。通常，您将得到50个不同的功能，你不知道它的必须的使用，这不应该的特殊情况下，这些建议更隐蔽的替代品，以及为什么他们必须要使用的外部使用方式。


• 的例子。有时候，他们比所有的休息
更重要

• 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

我知道如何绘制GTK +任意颜色的任意形状。我仍然不知道为什么绘制颜色的变化需要三个很长的code的非常模糊，非常直观行线。记住SVGAlib的的 setcolorRGB（R，G，B）;画（X1，Y1，X2，Y2）; 我觉得真的很难COM prehend拥有什么GTK +的作者的东西这么多复杂化。也许如果他们解释基本概念，而不是仅仅记录使用这些功能，我会理解的...

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...

又如：昨天我得到了，让我明白SQLite的答案。我理解的函数从列返回提取数据符号long long 。我明白了整数列可能是1,2,4,6和8个字节长。我明白我可以将列定义为无符号INT8或TINYINT。我并没有完全得到什么亲和的意思，我只知道都有过INTEGER的亲和力。我花了几个小时寻找时间戳是否应为UNSIGNED INTEGER或INT8，INT8是8位或8个字节，那是什么深奥的6个字节INT的名字吗？

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?

我错过的是，无符号INT8，TINYINT之类的都为INTEGER类型的语法糖的同义词（这始终是符号long long ），并给予长度是内部磁盘存储只能是自动，透明地调整，以适合比特数最少的价值，而且从侧面API完全看不见，交通不便。

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.

这篇关于你认为什么好的API文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！