Objectif C @property commentaires

Question

J'utilise Doxygen pour générer des documents pour mon code c objectif. Jusqu'à présent, cependant, je n'ai pas trouvé de lignes directrices sur la façon de documenter correctement les propriétés. Les exemples que j'ai regardés le font de toutes les façons imaginables. Certaines personnes documentent les variables elles-mêmes, certaines personnes documentent les déclarations @property. Certains utilisent //, tandis que d'autres utilisent des blocs complets/** * /.

Quelqu'un peut-il me diriger vers une référence pour les meilleures pratiques? Ou peut-être quelques informations sur la compatibilité future avec Doxygen? Je voudrais coller à un modèle qui, à tout le moins, sera facile à adapter à Doxygen une fois qu'ils développent un modèle officiel.

Answer 1

Tout ce que je peux dire est que le Core Plot framework annote déclarations de propriété dans la mise en œuvre en utilisant un format comme

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

et il semble produire des documents propres à l'aide Doxygen. De l'Core Plot documentation policy:

Le @property est nécessaire que doxygen ne peut pas trouver le nom de la propriété autrement.

propriétés accesseur comme en lecture seule, copier/conserver/assign et nonatomic sont automatiquement ajoutés et ne devraient pas se produire dans la partie manuelle de la documentation .

Answer 2

Vous trouverez ici des informations sur la convention de codage pour l'Objective-C: Google Objective-C Style Guide

Mais si vous voulez, il y a une autre bonne douce appelé HeaderDoc pour générer la documentation sous XCode. Vous pouvez vérifier son style de codage ici: HeaderDoc Tags

Answer 3

Mon expérience est:

Lorsque j'utilise la balise @property dans les commentaires, sortie doxygen des propriétés est corrompu comme: [ClassName]: [lire, écrire, attribuer]. La balise @property, et qui repose sur la déclaration de @property dans le code source, juste en dessous du bloc de commentaire, fonctionne correctement.

Par contre, @interface fonctionne bien pour les interfaces et @protocol fonctionne bien pour les protocoles.

Également, dans le passé, j'avais «glisser» doxygen sur certaines déclarations de protocole. Obj-C est-il encore un citoyen doxygène de seconde classe?

Note: J'utilise l'interface graphique/Assistant sur un Mac, et des blocs de commentaire utilise '!/* *' au lieu de '/ * *'.