很棒的小型 API/SDK 文档 [关闭]

Question

与here 有类似的问题，但我想通过这个我会得到一些结果并提供附加值。

作为一名 SDK 开发人员/提供者，我猜测应该在文档中写什么以及 SDK 的文档应该是什么样子。想到的不可避免的部分是：

• 整个类引用（包括属性、方法等）
• 每种方法的代码示例
• 如何使用代码 sn-ps 参考
• 示例例程和应用程序使编码器能够快速入门
• ????

请在您的回答中尝试提供至少 3 个指向您认为“很棒”的文档的链接，并提供一些信息说明原因。

如果您想针对特定语言，我的目标是 c# 开发人员，并且我的 SDK 包含一小组类 - 所以答案中的文档应该是相似的。 MSDN、DevExpress、Ogre - 只是一些我不想作为例子的例子，因为它们有很多 man-days，但它们都很棒。

谢谢

Answer 1

以 Java 和生物识别技术为例，使用 javadoc 构建的标准 API 文档（如 http://www.griaulebiometrics.com/javadoc/FingerprintSDKJava/com/griaule/grfingerjava/GrFingerJava.html 上的 Griaule 文档）包含开发人员需要的所有信息；而 DigitalPersona 有一个 PDF 文件，其中包含经过高度编辑的 API 描述，其中没有 Java 开发人员期望的从方法到类到字段的链接。

抛开语言和范式不谈，您的文档越开放；不试图隐藏任何东西，并使您的文档与实际产品保持同步，这会让您受到客户群的喜爱。

更具体地说，在您提出的问题答案中，整个班级的参考资料是最重要的。之后，一个使用大部分 API 的示例应用程序，并附有源代码。

Answer 2

良好的文档会花费时间。您必须意识到，从长远来看，您花在记录 API 上的每一分钟都会获得成百上千的回报。

话虽如此，是的，MSDN 至少对于 C# 开发人员来说是最好的参考，因为他们知道它并且它有效。