最直观、易读的 API/语言参考文档答案

【问题标题】：Most intuitive, readable API / language reference documentation最直观、易读的 API/语言参考文档
【发布时间】：2009-12-16 03:01:06
【问题描述】：

我正在处理一个项目可怕的最后阶段：为半技术人员编写 API。

我想知道：您发现哪些 API 文档特别优雅？

请注意，这与 API 本身的优雅程度无关：这纯粹是 API 文档本身的格式/外观问题。哪种语言或 API 文档以最直观、最易读的方式传达信息？

【问题讨论】：

标签： language-agnostic documentation formatting

【解决方案1】：

Python 有非常紧凑但非常清晰的文档：

http://docs.python.org/index.html

【讨论】：

【解决方案2】：

Django.

【讨论】：

【解决方案3】：

我将不得不使用MSDN Library。他们在记录方法的前置/后置条件方面做得特别好，并且在大量 API 中具有出色的一致性。

【讨论】：

【解决方案4】：

我一直很喜欢 Java standard library 的 javadocs 和教程。

【讨论】：

【解决方案5】：

我的头顶上有两个：

Zend Framework
Python（使用狮身人面像）

【讨论】：

【解决方案6】：

Flex...我真的觉得这种设置很完美。

【讨论】：

是的，这很好。非常类似于 javadocs，我也是它的粉丝。

【解决方案7】：

Python 的文档是我的最爱。

【讨论】：

【解决方案8】：

我的否定回答 - 只是为了记录我发现的可怕之处。

也许这只是主要生活在微软领域的一个例子，但我从未见过一种 API 文档语言可以像代码一样容易阅读。

我经常阅读的两个文档来源是 SQL Server 联机丛书和 MSDN C# 文档。我绝对讨厌两者都使用的技术文档语言。我发现几乎 100% 的时间我都会直接研究代码示例。

例如，下面是关于 select 的 t-sql 参考中的几行 - 我每天都在编写 select 语句，但真的很挣扎：

SELECT statement ::= 
    < query_expression > 
    [ ORDER BY { order_by_expression | column_position [ ASC | DESC ] } 
        [ ,...n ]    ] 
    [ COMPUTE 
        { { AVG | COUNT | MAX | MIN | SUM } ( expression ) } [ ,...n ] 
        [ BY expression [ ,...n ] ] 
    ] 
    [ FOR { BROWSE | XML { RAW | AUTO | EXPLICIT } 
            [ , XMLDATA ] 
            [ , ELEMENTS ]
            [ , BINARY base64 ]
        } 
]

只有在想要深入研究非常详细或边缘案例的需求时，我才会花时间重新学习文档语言的细节。但至少对我自己而言，实际的文档语法一旦满足了他们的需求就会消失。

编辑 - 我觉得有必要对 MSDN 有点积极，我每天都使用它，发现它是一个非常丰富的信息，但它通常是代码示例和解释性文本，而不是 API为我提供所需信息的文档。

【讨论】：

是的，我听说了。我有一个同事在我问之前给我看了 MSDN，不喜欢它的外观。
只是为了让您知道。代码示例是文档。它们本身不会神奇地出现在主题中。作者创建了文本和代码示例来演示如何使用某个功能/类/方法/等。
@Alexandra - 是的，他们当然是。添加好的代码示例和解释是微软文档多年来真正改进的地方。这就是我要强调的一点——对我来说，没有好的代码示例和解释性文本的文档很少足够。例如，我一直觉得 t-sql 语法示例中的技术语言很难阅读，我更喜欢代码示例。