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.