views:

1041

answers:

24

I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?

Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.

A: 

Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:

http://www.stack.nl/~dimitri/doxygen/results.html

Buggieboy
+5  A: 

My main criteria is - tell me everything I need to know and everything I'll ever want to know.

QT has pretty decent docs: http://doc.trolltech.com/4.5/index.html

Win32 MSDN is also pretty good although it didn't age well.

The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?

shoosh
Javadocs have a page for one class, so the methods and the class-summary is on one page.
Mnementh
I think he was referring to the .NET docs.
Steven Mackenzie
+1. QT docs are among the best I've ever seen - period.
Raj
+5  A: 

A good API will have the following characteristics:

  • Easy to learn
  • Easy to use, even without documentation
  • Hard to misuse
  • Easy to read and maintain code that uses it
  • Sufficiently powerful to satisfy requirements
  • Easy to extend
  • Appropriate to audience

The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:

///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }

API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.

James Jones
Sure, those are great examples of what makes a UI great, but the question is more about documentation than the API itself. I'd almost rather have a less well designed API that had way better docs, than a fantastic API with no descriptions that let you understand how fantastic it is. Well, almost... there is a lot of power in a good API.
Kendall Helmstetter Gelner
eglasius
+5  A: 

Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:

  • Very easy jump to docs from the API.

  • Well formatted and the code snippets you would want to copy and paste (like method signatures) stand out.

  • Links to projects with sample code right from the docs.

  • Automated document refresh mechanism, but by default docs are all local to start (so you can live with a flaky internet connection).

  • Easy way to switch between variants of documentation (to see different versions of the OS), and also select which sets of documentation to run searches against.

  • An overview section explains what the class is for, followed by a section breaking out methods grouped by purpose (methods to create and object, methods to query for data, methods to work with type conversions, etc), followed by the detailed method explanations.

I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.

Kendall Helmstetter Gelner
+2  A: 

First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.

The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.

Mnementh
+1 for reccomending the use of enums. In Java, [enums](http://java.sun.com/j2se/1.5.0/docs/guide/language/enums.html) are very powerful; it's like having a class with a fixed set of instances known at compile time. Unfortunately, many of Java's API's (Swing comes to mind) were designed before enums were a feature, and so use the int Enum pattern everywhere.
isme
+3  A: 

I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.

marcgg
+16  A: 

A good documentation MUST have:

  • datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
  • function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
  • an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
  • examples. Sometimes they are more important than all the rest

I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...

Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?

What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.

SF.
gbjbaanb
I was in an Android development class last quarter, and constantly ran into issues with their Javadocs. They would tell me that I needed to pass an SQLiteDBHelperFactory into some method, for instance, but never why (so I could know what I needed to construct). Turned out that I was just supposed to pass in `null`. *sigh*
Xiong Chiamiov
+1 for introduction and usage patterns. That's what I'm really missing with most Doxygen/Javadoc-creations
tstenner
@Xiong sounds like what would have helped even more is to make that parameter optional (or rather, make another version of the method that doesn't take that parameter).
MatrixFrog
Oh, certainly it could have been designed better. But they should have at least documented the design they did!
Xiong Chiamiov
A: 

i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!

I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?

Rob
+3  A: 

I think that a good API document needs to clearly explain:

  1. What problem this API solves
  2. When you should use it
  3. When you shouldn't use it
  4. Actual code showing "best practice" usage of the API

Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.

BenM
+1  A: 

I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.

What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.

BastiBense
I feel so too. QT Docs rock!
Raj
A: 

Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:

Unity Application Block (Go to the Download section for the CHM)

All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.

Slavo
+3  A: 

I personally believe a perfect example of good documentation is PHP's documentation:

For an example: http://www.php.net/manual/en/function.fopen.php

I think effective documentation includes:

  • Parameter listing
  • (Useful) description of the parameter
  • If they parameters are a string, list out and EXPLAIN every possible possible parameter
  • Return values on both successful execution and non-successful execution
  • Any exceptions/errors it can raise
  • Examples (THE MOST IMPORTANT imo)

Optionally:

  • Changelog
  • Notes/Examples from other users

Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.

What is think is an example of a alright documentation is Python's: http://docs.python.org/py3k/library/array.html

It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.

Nathan Adams
The php manual is my favorite documentation. man pages are also good. man man.
drawnonward
The upside with the PHP examples: the URIs are easy to remember ("php dot net slash array" or whatever). The downside: some of the comments contain crazy, out-of-date poor code examples and should be taken with a bagful of salt!
Tom Morris
A: 

The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.

Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.

I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.

Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).

Alexander Babaev
+2  A: 

Good documentation should have at least the following:

  • When an argument has additional limitations beyond its type, they need to be fully specified.
  • Description of the [required] state of an object before calling the method.
  • Description of the state of an object after calling the method.
  • Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
    • Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
    • Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.

In addition, the following are useful:

  • Description of the state of an object if an exception is thrown by the method.
  • Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
  • Example usage.

Based on this:

  • An example of great documentation is the MSDN library.
    • To be fair, the online version of this does suffer from difficulty of navigation in cases.
  • An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
280Z28
A: 

Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.

I would definitely recommend watching Josh Bloch's presentation about this: http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw

This covers not only what you're looking for but much more.

mindas
+3  A: 

Just a few thoughts...

  1. Examples - win32 API documentation is better than iPhone's because of:

    • (short) code examples

    I vote for any API doc with small and make-sense examples

  2. Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes

    • good API is solving real world problems and there should be some meaningful examples

  3. Don't auto-gen doc

    • documentation should not be done during writing code (or by the same guy)
    • doc is for a stranger, whom the programmers usually don't care of

  4. Avoid ___V2 version of API

    • but it's not a doc issue
ohho
+1  A: 

I find Google APIs a beautiful example of Good documentation API.

They have:

  1. Bird's eyes view of the entire APIs structure
  2. Overviews of the main features of the single API
  3. Nice and colored examples for a quick feedback
  4. Detailed references
  5. A blog that keep you updated
  6. A google groups that documents problems and solutions
  7. Videos
  8. FAQ
  9. Articles
  10. Presentations
  11. Code Playground
  12. A search engine to crawl inside a pile of documentation

That's it! When i play with google APIs documentation site, i feel at home.

systempuntoout
Ugh seriously? I developed a Google Checkout solution last year and their API documentation was the worst I've ever come across. The navigation made absolutely no sense, the examples weren't correct compared to what the server was returning and their "support documentation" is horrendous - I've been waiting for 6 months for them to fix an issue with my account, and every time I e-mail them they just say they'll look into it and never get back to me. For a business-critical function this is an epic fail from a very large company - I'll stick with the smaller guys, thanks.
Andy Shellam
@Andy Wow, a little bit harsh :).For the support\issues i really can't say; for the documentation per se, i really like how it is structured\organized but again, i could imagine that handling such pile of documentation is hard to keep it clean and errorfree.Thanks to have shared your experience.
systempuntoout
Yeah I've had it with Google. Their documentation was really detailed, if a little unstructured in navigation terms, but they changed it recently and it's got absolutely no flow to it any more. As for support, there isn't even a phone number to ring them, and it takes them a couple of days to send an unhelpful reply to an e-mail. Like I say it's not good enough for a business-critical function as credit card payments. I've not used any other Google API so I do admit I'm a little biased from one bad experience, but that's all it takes lol.
Andy Shellam
+1  A: 

Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.

It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.

The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.

Answer the question: "how do I do X with Y?" You may know the answer. I don't.

Tom Morris
+2  A: 

One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?

This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.

ZorbaTHut
+1  A: 

Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?

Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.

@author:

  • Who wrote this? Who's proud of it? Who should be ashamed of their work?

Interface level documentation tells me:

  • what should this do?
  • what will it return?

Implementation level documentation tells me:

  • how does it do it? what kind of algorithm? what sort of system load?
  • what conditions might cause a problem? will null input cause an issue? are negative numbers okay?

Class level documentation tells me:

  • what goes here? what kind of methods should I expect to find?
  • what does this class represent?

@Deprecated tells me:

  • why is this planned for removal?
  • when is it expected to be removed?
  • what is the suggested replacement?

If something is final:

  • why didn't you want me to extend this?

If something is static:

  • remind me in the class level doc, at least implicitly.

In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.

As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.

Dean J
A: 

Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.

Aaron Mc Adam
A: 

IMO examples are the best documentation.

armandino
A: 

The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.

API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.

licorna
+1  A: 

I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.

Daniel