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.
精彩评论