Skip to main content

What's your preferred form of API documentation?

Javadocs
69% (455 votes)
Verbose method and parameter names
11% (72 votes)
Separate tutorial documents
18% (120 votes)
Something else
2% (16 votes)
Total votes: 663

Comments

Java Tutorials

I prefer java tutorials to learn easily and perfectly

The Java Class Libraries book series

Great stuff, unfortunately only up to JDK 1.2.

JavaDoc is a king

Hi people, if you don't do .NET programming you probably do not appreciate JavaDoc enough! JavaDoc is damn good compared to .NET API docs. Some simple things that we take as common (like speed, good navigation, default values for parameters in overloaded methos, boundary conditions, thread-safety notes etc. are often missing in .NET API docs...

JavaDoc is a king

I used to develop with the .NET Framework SDK, you are right .NET documentation is less practical than java's documentation. Many Java developers can observe the assets of javadoc in his dayly life, I think that javadoc principle should become a standard in terms of API documentation. (notice : a very good support of javadoc is provided in NetBeans 5.0)

JavaDoc is a king

I used to develop with the .NET Framework SDK, you are right .NET documentation is less practical than java's documentation. Many Java developers can observe the assets of javadoc in his dayly life, I think that javadoc principle should become a standard in terms of API documentation. (notice : a very good support of javadoc is provided in NetBeans 5.0)

favorite for of documentation

Verbose method and parameter names, because good code should read like documentation! javadoc is very useful too.

Others = all

API for the technical details, tutorials to show the usage, philosopy and common use cases and verbose names to make it easy to remember.... so, given the choice: all.

Otherwise a good Javadoc is the minimum, but usually not enough. < br /> S!

HOW COME no UML?!

How come UML wasn't in the list of choices?

HOW COME no UML?!

UML is good for visualizing high level picture of something, it's not that good at documenting or specifying gory API details.

HOW COME no UML?!

You're right. The question is about API documentation (and UML can't do that). At least I managed to lure someone into making one more comment!

Both

Tutorials and Javadocs!

FIrst things first

Where something is documented is not as important as what is documented - as long as it can be easily found.

Several J2SE class documentations are extremely bad. The worst are the ones where each method is documented in isolation, and only with a single sentence or two, but where the documentation not at all explains how all the methods are supposed to work together. Where the sequence of method calls is not clear and where the documentation is not capable of communication the idee the developer had when structuring a class in a particular way.

Also typically final static int constants are often individually explained in isolation and not even properly referenced in the method documentation where the constants are supposed to be used as arguments.

Equally "fun" are class documentations where the terminology is not explained. Particularly when the class developer worked from a very generic abstraction which doesn't map in a straight forward way to a real-world problem.

A class documentation might be formally complete if each public and protected slot is decorated with some sentence, but that documentation is useless as long as the information does not easily allow a developer to form a mental model of what is going on. Here several Java APIs fail miserable. It is maybe not a good idea to let the software developer also write the documentation.

Abother issue are code examples. I like to have code examples in the documentation. But not primarily the demonstration of "cool", esotheric features, but the plain vanilla usage of a class. The most common, obvious cases first. Then the common but not so obvious usage. And then we can talk about the rest.

Currently the code examples in the tutorials are even worse than the ones in the javadoc. The javadoc examples often only suffer from the problem mentioned in the previous example. However, the tutorial examples often demonstrate very bad coding practice. In order to keep an example short to many shortcuts are taken. That plus the fact that the tutorial examples are often extremely artificial, tool.

All three used at different times

Some sample code and an easy to follow tutorial is great for starting off and is better than just reading the Javadoc when learning a new API. Once I'm using an API the I use the Javadoc as a reference and for discovering additional features.

Tutorials AND Javadoc.

I always look for tutorials to learn the ropes of a new (to me) package or component. (Those nice JAXWS 2 lessons come to mind.) I use the Javadocs a lot when I have specific doubts (Could a certain method return null?)

preferred doc method

Good class and method names can help to reduce the need to consult the javadocs. They all work together to simplify and speed developement.

Why not all three of them!

Method and parameter name are very useful when well chosen.

I definitely consult the javadoc when what does the method is not so obvious.

And then, when the proper usage requires more then only the basics understanding, I consult tutorials... If JUnit test is available it may be a good start too.