J'utilise Doxygen pour générer des documents pour mon code C objectif. Jusqu'à présent cependant, je n'ai pas été en mesure de trouver des lignes directrices pour savoir comment documenter correctement les propriétés. Des exemples que j'ai examinés le font tous les sens imaginables. Certaines personnes documentent les variables elles-mêmes, certaines personnes documentent les déclarations de @property. Quelques utilisations //, tandis que d'autres utilisent des blocs complets / ** * / blocs.
Quelqu'un peut-il me dire une référence pour les meilleures pratiques? Ou peut-être des informations sur la compatibilité future avec Doxygen? J'aimerais m'en tenir à un schéma qui, à tout le moins, sera facile à adapter à Doxygen une fois qu'ils développent un modèle officiel.
3 Réponses :
Ici, vous trouverez ici des informations sur la convention de codage pour l'objectif-C: Guide de style Google Objective-C
Mais si vous le souhaitez, il existe un autre bon doux appelé Headerdoc pour générer une documentation sous Xcode. Vous pouvez vérifier son style de codage ici: Tags HeaderDoc
Des références utiles et j'ai voté, mais je ne réponds pas vraiment à aucune de mes questions. Le Google Doc omet des lignes directrices pour les commentaires @Property et Headerdoc est certainement une solution alternative mais pas une solution pour moi.
Tout ce que je peux dire, c'est que le cadre de tracé de base annotons les déclarations de propriété dans le Mise en œuvre à l'aide d'un format comme et il semble produire une documentation propre à l'aide de Doxygen. De Politique de documentation de la parcelle de base : Le @Property est requis comme DOXYGEN
Impossible de trouver le nom de la propriété
sinon.
Propriétés de l'accesseur comme Readonly,
copier / retenir / assigner et nonatomic sont
ajouté automatiquement et ne devrait pas
se produire dans la partie manuelle de la
Documentation.
Mon expérience est la suivante:
Lorsque j'utilise l'étiquette @Property à l'intérieur des commentaires, la sortie Doxygen des propriétés devient corrompue comme: [Nom de classe]: [Lire, écrire, Attribuer].
Si je ommit l'étiquette @property, et comptez plutôt sur Doxygen, puis sur la déclaration "@property" dans le code source, juste en dessous du bloc de commentaire, tout fonctionne bien.
En revanche, @interface fonctionne bien pour les interfaces et @protocol fonctionne bien pour les protocoles.
Aussi, dans le passé, j'ai eu Doxygen 'Slip' sur certaines déclarations de protocole. Obj-C est-il toujours un citoyen Doxygen de deuxième classe?
Remarque: j'utilise l'interface GUI / Wizard sur un Mac et des blocs de commentaires utilisent '/ * * !' au lieu de '/ * *'.