Objective C @property comments

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 othe开发者_如何学编程rs 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.

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.

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

My experience is:

When I use the @property tag inside the comments, doxygen output of the properties becomes corrupted like: [ClassName]:[read, write, assign].

If I ommit the @property tag, and instead rely on doxygen finding the '@property' declaration in the source code, right below the comment block, everything works fine.

In contrast, @interface works fine for interfaces and @protocol works fine for protocols.

Also, in the past, I had doxygen 'slip' on some protocol declarations. Is Obj-C still a second-class doxygen citizen?

Note: I am using the GUI/Wizard on a Mac, and comment blocks use '/**!' instead of '/**'.