API documentation
Jun 4th, 2008 by ellen
Most of the time, I work with various APIs. The quality of the API documentation significantly influence my efficiency. My favourite is the cookbook-ish API doc always with some quintessential examples showing how to use the API calls to accomplish a certain task. A cookbook-ish User-Howto plus API reference listing the UMLs of the API architecture and method explainations would be almost perfect. However most API docs only provides the latter part, this really reduces the effectiveness and expressiveness of the API doc.
When I work with Java, The Java Developers Almanac is indispensable. If only the javadoc were constructed like that from the very beginning. The official javadoc of many methods do not clearly tell how should the methods be correctly called, or how should a group of methods to be called together. My experience with the Xerces-C++ API doc was a lot worse. By reading the doc of DOMDocumentTravesal class, I simply did not grok how should the parameters of the createTreeWalker() method normally look like. I had to download the sample sources and dig around. Finally there was that precious line burried in several hundreds of exception-handling lines and I could write my own calls imitating that every example line. Imitating was not really adequate, I had to guess/try/debug for serveral times. Sign, why don’t they put an example of just two or three lines right inside the class doc? Beside that, the html layout of the Xerces-C++ API doc is not optimal. Try to click a method name, page will take you to the detailed explaination, just see how much time your eyes need to capture the first line of the detailed method explaination. It is painful when my eyes search around in such an unsharp layout of method docs hundred times a day. The sample sources of Xerces-C++ are not efficient for reference purpose. Just much too much UI and exception handling code, not easy to locate the lines which I really need to look up. Or maybe I’m too dumb a programmer. Anyway I will remind myself, if I were going to put up API docs, never, ever make it look like the Xerces-C++ API doc!
There are good API docs though. For example the 800+ pages Adobe Framemaker FDK Programmer Reference contains hundreds of quintessential, howto-oriented small examples. Other good API docs that have efficiently helped me out are, Drools user manual, Seam user manual (the example projects comes with the Seam distributions significantly flatten the learning curve), MySql user manual, iText doc, Groovy doc.
