Voici un exemple de toutes les options que j'ai trouvées depuis Xcode 5.0.2
Cela a été généré avec ce code:
/** First line text.
Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!
@a Italic text @em with @@a or @@em.
@b Bold text with @@b.
@p Typewritter font @c with @@p or @@c.
Backslashes and must be escaped: C:\\foo.
And so do @@ signs: user@@example.com
Some more text.
@brief brief text
@attention attention text
@author author text
@bug bug text
@copyright copyright text
@date date text
@invariant invariant text
@note note text
@post post text
@pre pre text
@remarks remarks text
@sa sa text
@see see text
@since since text
@todo todo text
@version version text
@warning warning text
@result result text
@return return text
@returns returns text
@code
// code text
while (someCondition) {
NSLog(@"Hello");
doSomething();
}@endcode
Last line text.
@param param param text
@tparam tparam tparam text
*/
- (void)myMethod {}
Remarques:
- Les commandes doivent être dans un
/** block */
, /*! block */
ou le préfixe ///
ou //!
.
- Les commandes fonctionnent avec le préfixe
@
( style headerdoc ) ou \
( style doxygen ). (Ie @b
et les \b
deux font la même chose.)
- Les commandes viennent généralement avant l'élément qu'elles décrivent. (Autrement dit , si vous essayez de documenter une propriété, le commentaire doit précéder le
@property
texte.) Ils peuvent venir par la suite, sur la même ligne, avec /*!<
, /**<
, //!<
, ///<
.
- Vous pouvez ajouter de la documentation aux classes, fonctions, propriétés et variables .
- Toutes ces commandes apparaissent en texte vert foncé pour indiquer qu'il s'agit de commandes valides, à l'exception de
@returns
.
- Vous devrez peut-être créer votre projet (ou redémarrer Xcode) avant que les dernières modifications apportées à votre documentation n'apparaissent.
Où voir la documentation:
1. Pendant la fin du code, vous verrez le bref texte:
Cela affichera le texte bref (sans mise en forme); s'il n'y a pas de texte bref, il affichera une concaténation de tout le texte jusqu'au premier @bloc; si aucun n'existe (par exemple, vous commencez par @return), alors il concatera tout le texte en supprimant toutes les commandes @.
2. Option-clic sur un nom d'identifiant:
3. Dans le panneau Inspecteur d'aide rapide
(Voir la première capture d'écran.)
4. Dans Doxygen
Étant donné que les commandes de Xcode 5 sont compatibles avec Doxygen, vous pouvez télécharger et utiliser Doxygen pour générer des fichiers de documentation.
Autres notes
Pour une introduction générale à Doxygen et comment documenter le code Objective-C, cette page semble être une bonne ressource.
Descriptions de certaines des commandes prises en charge:
@brief
: insérera du texte au début du champ de description, et est le seul texte qui apparaîtra pendant la complétion du code.
Les éléments suivants ne fonctionnent pas:
\n
: ne génère pas de nouvelle ligne. Une façon de créer une nouvelle ligne est de s'assurer que rien ne se trouve sur cette ligne. Pas même un seul caractère d'espace!
\example
Les éléments suivants ne sont pas pris en charge (ils n'apparaissent même pas en vert foncé):
- \citer
- \ docbookonly
- \ enddocbookonly
- \ endinternal
- \ endrtfonly
- \ endsecreflist
- \ idlexcept
- \ mscfile
- \ refitem
- \ relatedalso
- \ rtfonly
- \ secreflist
- \court
- \fragment
- \table des matières
- \ vhdlflow
- \ ~
- \ "
- .
- ::
- \ |
Mots clés réservés Apple:
Apple utilise ce qui semble être des mots-clés réservés qui ne fonctionnent que dans leur documentation. Bien qu'ils apparaissent en vert foncé, il semble que nous ne pouvons pas les utiliser comme Apple le fait. Vous pouvez voir des exemples d'utilisation d'Apple dans des fichiers tels que AVCaptureOutput.h.
Voici une liste de certains de ces mots-clés:
- @abstract, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref.
Au mieux, le mot-clé provoquera une nouvelle ligne dans le champ Description (par exemple @discussion). Au pire, le mot-clé et tout texte le suivant n'apparaîtront pas dans l'aide rapide (par exemple @class).