Objective C @property comments

Question

I use Doxygen to generate docs for my objective c code. Up to now though, I haven't been able to find any guidelines for how to correctly document properties. Examples I've looked at do it every conceivable way. Some people document the variables themselves, some people document the @property declarations. Some use //, while others use full /** */ blocks.

Can anyone point me to a reference for best practices? Or maybe some information about future compatibility with Doxygen? I would like to stick to a pattern that, at the very least, will be easy to adapt to Doxygen once they develop an official pattern.

Answer 1

All I can say is that the Core Plot framework annotates property declarations in the implementation using a format like

 /** @property myProperty
 *   @brief Property is very useful
 *   Useful and there is a lot more to tell about this property **/

and it seems to produce clean documentation using Doxygen. From the Core Plot documentation policy:

The @property is required as doxygen cannot find the property name otherwise.

Accessor properties like readonly, copy/retain/assign, and nonatomic are automatically added and should not occur in the manual part of the documentation.

Answer 2

Here you can find some information about the coding convention for the Objective-C: Google Objective-C Style Guide

But if you want, there is an other good soft called HeaderDoc to generate documentation under XCode. You can check its coding style here: HeaderDoc Tags