CODEWITHSUNDEEP
iphoneobjective-ccommentsdoxygen
DougW
DougW

Reputation: 30025

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 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.

Upvotes: 9

Views: 3864

Answers (3)

Nicolas Miari
Nicolas Miari

Reputation: 16246

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 '/**'.

Upvotes: 1

Brad Larson
Brad Larson

Reputation: 170319

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.

Upvotes: 11

Yannick Loriot
Yannick Loriot

Reputation: 7136

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

Upvotes: 4

Related Questions