最直观，可读的API /语言参考文档

Question

我正在研究项目可怕的最后阶段：为半技术人员记录API。

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

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

Answer 1

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

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

Answer 2

Django.

Answer 3

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

Answer 4

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

Answer 5

我的头顶两个：

• Zend Framework
• Python（使用Sphinx）

Answer 6

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

Answer 7

我的否定回答 - 只记录我发现的可怕内容。

也许这只是一个主要生活在微软领域的案例，但我从来没有见过一种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提供我需要的信息的文档。

Answer 8

Python的文档是我最喜欢的。