Eyes, JAPAN Blog > Documenting Objective-c with Doxygen

Documenting Objective-c with Doxygen

will

この記事は1年以上前に書かれたもので、内容が古い可能性がありますのでご注意ください。

Today, Denis sent me an useful webpage about how to document the Objective-c with Doxygen.
It is important to document the code when developing. The class, methods, parameters,and returen values should be documented to make the class and methods easy to be reused by other developers. Java has the javadoc, ruby has RDoc, PHP has phpDocumenter,etc. They can automatic generate the code documents for these programming language. 
The objective-c language also has this kinds of tools to generate the documents, such as AutoDoc, HeaderDoc, and Doxygen[1]. The Doxygen is a better tool to make objecitive-c source code.
Here, We use Doxygen’s JAVADOC_AUTOBRIEF setting, which mimics some of Javadoc’s behavior. The comments are something like java’s comments.
For multi-row comments, we use as follows:
/**
Simple class to represent an automobile.
*/
@interface Automobile : NSObject {}

For single-row comment, we use as follows:
int i; /**< An integer value */

For parameters or return value of a method, we use @param tag and @return tag. As follows:
/**
Calculates the volume of a cylinder
@param r the radius
@param h the height
@returns the volume
*/
double cylinderVolume( double r, double h );

There are a number of additional tags we can use in the bodies of our comments to give the reader more information. Here’s a list of popular javadoc style tags that Doxygen supports:

@author name | URL | email address
Use this tag to claim ownership of a portion of the code base. This supports adding a name, URL, or email address.

@deprecated text
Use this to indicate that the commented piece of code will be removed at some point in the future.

@exception type text
Use this to indicate that the commented piece of code may thrown an exception.

@see text | URL | classname | classname#methodname
Use this to tag to refer the reader to some other source of related information.

@since text
Add a note describing at what point this part of the interface became available.

Since now, we know how to comment our objective-c code. Then next is how to use Doxygen to generate the comments.
There are two ways to automatic generate the comments. One is directly use the Doxygen. Another one is add a script which call the Doxygen to extract the comments from source codes when building the Xcode projects.
The two kinds of methods are shown in the reference webpage.

Doxygen.tiff

Reference:

1. http://www.duckrowing.com/2010/03/18/documenting-objective-c-with-doxygen-part-i/

Comments are closed.