Objective C @propiedad comentarios

Question

Yo uso Doxygen para generar documentos para mi objetivo código c. Hasta ahora, no he podido encontrar ninguna guía sobre cómo documentar correctamente las propiedades. Los ejemplos que he analizado lo hacen de todas las formas imaginables. Algunas personas documentan las variables por sí mismas, algunas personas documentan las declaraciones @property. Algunos usan //, mientras que otros usan bloques completos/** * /.

¿Alguien me puede indicar una referencia de las mejores prácticas? ¿O tal vez alguna información sobre la futura compatibilidad con Doxygen? Me gustaría mantener un patrón que, al menos, sea fácil de adaptar a Doxygen una vez que desarrollen un patrón oficial.

Answer 1

Todo lo que puedo decir es que el Core Plot framework anota declaraciones de bienes en la aplicación utilizando un formato como

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

y parece producir la documentación limpia usando Doxygen. Desde el Core Plot documentation policy:

Se requiere que el @property como doxygen no puede encontrar el nombre de la propiedad lo contrario.

propiedades Accessor como de sólo lectura, copiar/mantener/remisión, y no atómica se añaden automáticamente y no deben ocurrir en la parte manual de la documentación .

Answer 2

Aquí puede encontrar información acerca de la convención para la codificación de Objective-C: Google Objective-C Style Guide

Pero si quieres, no es otro buen blando llamado HeaderDoc para generar la documentación bajo XCode. Se puede consultar su estilo de codificación aquí: HeaderDoc Tags

Answer 3

Mi experiencia es:

Cuando uso la etiqueta @property el interior de los comentarios, la salida doxygen de las propiedades se daña como: [NombredeClase]: [leer, escribir, asignar].

Si omite la etiqueta @property, y en cambio confío en que doxygen encuentre la declaración '@property' en el código fuente, justo debajo del bloque de comentarios, todo funciona bien.

Por el contrario, @interface funciona bien para interfaces y @protocol funciona bien para protocolos.

Además, en el pasado, tuve doxygen 'slip' en algunas declaraciones de protocolo. ¿Sigue siendo Obj-C un ciudadano doxygen de segunda clase?

Nota: Estoy usando la interfaz gráfica de usuario/Asistente en un Mac, y los bloques comentario por favor utilice '!/ * *' en lugar de '/ * *'.