Good documentation goes a long way towards, not only helping others understand your code, but also simplifying re-use. Unfortunately, it seems that the moment documentation is written, it’s out-of-date from the code, especially if maintained separately in its own document.
When Sun Microsystems introduced Java, they also introduced Javadoc, which let their engineers, and other Java developers, document APIs “in-line”, next to the method definitions. Javadoc uses a simple markup language, embedding the documentation for a method within a
/** … */ comment block. Typically a Javadoc block starts with a sentence or two describing the purpose of the method or function. The purpose of parameters passed into the method are marked by
@param followed by the parameter name and its description. Finally the comment block ends with a description of the return value, preceded by
@return. This documentation lives in the class interface definition, making it easy to maintain at the same time as the code, ensuring that it remains up to date. The Javadoc tool can easily parse the source files, producing human-friendly, HTML documentation of the library classes.
Gentle Bytes’ excellent appledoc tool brings this easy documentation approach to Objective-C development. Simply comment the methods in your class definitions (.h) and run the appledoc application to compile beautiful documentation that both matches the format of Apple’s framework documentation and integrates directly into Xcode. Claus Broch provides a great blog outlining how to integrate the execution of appledoc directly into Xcode, further simplifying your documentation efforts.
Appledoc provides a simple and lightweight way to document your Objective-C code, making it easier for both you and others to understand and re-use your code.