| layout | title | ref | rating |
|---|---|---|---|
post |
Documentation |
9.1 |
There's an adage among Cocoa developers that Objective-C's verbosity lends its code to being effectively self-documenting. Between longMethodNamesWithNamedParameters: and the explicit typing of those parameters, Objective-C methods don't leave much to the imagination.
But even self-documenting code can be improved with documentation, and just a small amount of effort can yield significant benefit to others.
Listen—I know programmers don't like to be told what to do, and prescriptive arguments of "thou shalt" and "thou shalt not" have the rhetorical impact of a trombone, so I'll cut to the chase:
Do you like Apple's documentation? Don't you want that for your own libraries? Follow just a few simple conventions, and your code can get the documentation it deserves.
Every modern programming language has comments: non-executable natural language annotations denoted by a special character sequence, such as //, /* */, #, and --. Documentation provides auxiliary explanation and context to code using specially-formatted comments, which can be extracted and parsed by a build tool.
In Objective-C, the documentation tool of choice is appledoc. Using a Javadoc-like syntax, appledoc is able to generate HTML and Xcode-compatible .docset docs from .h files that look nearly identical to Apple's official documentation.
Doxygen, used primarily for C++, is another viable option for Objective-C, but is generally dispreffered by the iOS / Mac OS X developer community.
Here are some examples from well-documented Objective-C projects:
Objective-C documentation is designated by a /** */ comment block (note the extra initial star), which precedes any @interface or @protocol, as well as any method or @property declarations.
For classes, categories, and protocols, documentation should describe the purpose of that particular component, offering suggestions and guidelines for how it should be used. Structure it like a news article: start with a top-level "tweet-sized" overview, and then explore further topics in more detail as necessary. Concerns like how a class should (or should not) be subclassed, or any caveats in behavior for standard protocols (like NSCopying) should always be documented.
Each method should similarly begin with a concise description of its functionality, followed by any caveats or additional details. Method documentation also contains Javadoc-style @ labels for common fields like parameters and return value:
@param [param] [Description]: Describes what value should be passed for this parameter@return [Description]: Describes the return value of the method@see [selector]: Provide "see also" reference to related method@warning [description]: Call out exceptional or potentially dangerous behavior
Properties are often described in a single sentence, and should include what its default value is.
Related properties and methods should be grouped by an @name declaration, which functions similarly to a #pragma mark, and can be used with the triple-slash (///) comment variant.
Try reading other documentation before writing some yourself, in order to get a sense of the correct tone and style. When in doubt about terminology or verbiage, follow the lead of the closest thing you can find from Apple's official docs.
To help speed up the process of documenting your project, you may want to check out the VVDocumenter-Xcode project, which automatically adds
@paramand@returnlabels for methods according to their signature.
Just by following these simple guidelines, you can add great-looking, informative documentation to your own project. Once you get the hang of it, you'll find yourself cranking docs out in no time.
Thanks to @orta for suggesting this week's topic, and for his ongoing work on CocoaDocs which provides automatically-generated documentation for projects published on CocoaPods.