开发者

Most intuitive, readable API / language reference documentation

I'm working on the dreaded last stage of a project: documenting the API for a semi-technical开发者_开发百科 audience.

I'm wondering: what API docs have you found to be particularly elegant?

Note that this has nothing to do with how elegant the API itself is: this is purely a question of the formatting/appearance of the API docs themselves. Which language or API docs convey their information in the most intuitive and readable way?


Python has very compact, but amazingly clear documentation:

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


Django.


I'm going to have to go with the MSDN Library. They do a particularly good job of documenting pre/post conditions of methods and excellent consistency across a HUGE set of APIs.


I've always liked the javadocs and tutorials for the Java standard library.


Two off the top of my head:

  • Zend Framework
  • Python ( uses Sphinx )


Flex...I really find this sort of setup perfect.


Python's documentation is my favorite.


A negative answer from me - just to document what I've found horrible.

Maybe it is just a case of living mostly in Microsoft land but I've never seen an API documentation language that I can read as easily as code.

The two documentation sources I read regularly are the SQL Server Books Online and the MSDN C# documentation. I absolutely loathe the technical documentation langauges employed on both. I find that almost 100% of the time I dive straight to code examples.

For example, below is a few lines from the t-sql reference on select - I write select statements every day yet really struggle with this:

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 ]
        } 
] 

It is only in the case of wanting to dig into a very detailed or edge case requirement that I ever take the time to relearn to details of the documentation language. But for myself at least, the actual documentation syntaxes evaporate once they've served their need.


EDIT - I felt the need to be a little bit positive about MSDN, I use it most every day and find it to be a great wealth of information, but it is generally the code samples and the explanatory text, not the API documentation that give me the information that I need.

0

上一篇:

下一篇:

精彩评论

暂无评论...
验证码 换一张
取 消

最新问答

问答排行榜