The Little Things, Like Good documentation
Over time having good documentation can have subtle effects on the flow of what you produce in an environment and how enjoyable it is to program for that environment. As someone who programs in Java and in Cocoa it seems worth it to point out the differences in how the API documentation is laid out. I’m gonna explain why Apple’s Cocoa docs are better than Sun’s (uh, I mean Oracle’s) Java docs, and why I always dread having to look something up in the Java API.
We will be comparing JWindow with NSWindow. Both documentation sources are created with document genertation tools. Apple uses HeaderDoc for their API and Sun (errr, Oracle) uses JavaDoc for their API.
Method Overview
The first noticeable and most important difference is the method overview for each. Java documentation is in alphabetical order. Cocoa documentation has been organized into logical groups. Organization is important because the most common thing you do as a programmer is look for a method that does what you want to do. When you are unfamiliar with the methods on a class or haven’t used the class for a while all you know is “I want to do X”. Grouping the methods into categories of actions makes it easier for the uninitiated to find what they are looking for.
Method documentation in Java
Method documentation in Cocoa
You might be thinking “Hey, wait a minute, the cocoa documentation looks cleaner but where are the method parameters, return types and method description?” The method parameters and return types aren’t that important when you’re looking for what will do the job. If you need to know them you can click on the method to get more detailed information. The method description is important and is displayed when you mouseover the method link. By removing visual clutter the Cocoa documentation makes it easier to find what you need.
Displaying a method description with a mouseover
Super class methods
Super class methods are handled differently also. In Cocoa, they simply aren’t there. If you want to see the methods on the super class then you must navigate to the definition of the super class. In JavaDoc, however, there is a less than useful dump of all the methods of all the super classes in a highly unreadable form. This can create a lot of visual garbage that you have to scroll over.
A summary of super class methods in JavaDoc
Conclusion
The point here is a point that has been made in the past “API Design Matters”. Not only should it be well documented, but that documentation should be an easy to use reference.