My dear wife has just started to learn to use Java in her work and asks me a lot of questions as she begins her journey in this wonderful language. To almost all her questions my answer is the same: "See Javadoc."

In addition to being a way of avoiding having to find or know the answer, it constantly surprises me what is available in the Javadoc and how useful a source of information it can be.

When I began to use Java in 1998 I received the pointer of the Java API Specification, or Javadoc, from a colleague. Despite the limitations of the JDK 1.1 Javadoc style when compared to Java 2, I immediately found that it was much more helpful than my other reference books. The books might help you get started on Java but, once you're serious, the Javadoc is something I know I can't live without.

The obvious benefit of using Javadoc is getting the most accurate and detailed description of Java APIs. Most likely the Javadoc is written by Java API implementers who know the behavior of the API inside-out. When the API changes, so does the Javadoc, whereas books, tutorials, and other sources lag behind. To know how a mehod works, asks the author who committed the doc and code together.

To ensure that different vendors' Java implementations uphold Java's fundamental tenant of "write once, run anywhere," Javadoc plays a part too. For any implementation to claim that it is compatible to a certain Java specification, it must pass the conformance test suite, sometimes called Technology Compatibility Kit (TCK). Each test in the TCK is strictly written according to the Javadoc, and nothing else, to make sure that the behavior of an implementation conforms. So if your application relies solely on behaviors described in Javadoc, you not only leverage the TCK effort but also have the maximum assurance that the application will work across different Java implementations. On the other hand, un-Javadoc'ed behaviors are likely implementation dependent and subject to change in future releases. If your application relies on any of these, the guarantee of "write once, run everywhere" may no longer hold.

Javadoc is a "living" document, as it is continuously being updated and maintained. At Sun, a lot of change requests of Javadoc are filed by development teams and customers during the development of a new release of a Java technology. These include requests for API semantic changes, behavior clarifications, or are as simple as grammar or spelling corrections. Regardless of how trivial it is, each change request to Javadoc is treated seriously. Some of them have to go through thorough reviews and approvals. Each new release of a Java technology is often accompanied by hundreds of Javadoc improvements, so by using Javadoc you leverage all these efforts.

Today's Javadoc is more complete than ever. The String.substring() story is just one example, but if you have other questions, such as "What is the behavior of this method if the parameter is null?" or "Does this method throw IllegalArgumentException or IndexOutOfBoundException if the index is invalid?", take a look at the Javadoc and seek the answers there.

Javadoc is by no means perfect. You may find that an API's description lacks certain aspects or is not clear enough. Should you feel that way, the developer who implements this API may have felt the same and chosen his own interpretation in the API's implementation. The result is different behaviors across different implementations. It is important therefore that, as an API consumer, you file Javadoc change requests at http://bugs.sun.com/services/bugreport/index.jsp. Remember, a more precise and definitive Javadoc will result in more conformant Java implementations, which in turn increase the chance that your applications can run across different platforms.

So what can you do with Javadoc? See it, rely on it, and improve it.