Quelles sont les nouvelles commandes de documentation disponibles dans Xcode 5?

Question

L'une des nouvelles fonctionnalités de Xcode 5 est la possibilité de documenter votre propre code avec une syntaxe de commentaire spéciale. Le format est similaire à Doxygen, mais semble ne prendre en charge qu'un sous-ensemble de ces fonctionnalités .

Quelles commandes sont supportées, et lesquelles ne le sont pas?
Est-ce que l'un de leurs usages diffère de Doxygen?

Answer 1

Voici un exemple de toutes les options que j'ai trouvé comme de Xcode 5.0.2

Qui 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 {}

Notes:

• Les commandes doivent être dans un /** block */, /*! block */, ou avec le préfixe /// ou //!.
• Les commandes de travail avec l' @ (headerdoc style) ou l' \ (doxygen style) préfixe. (I. e. @b et \b à la fois faire la même chose.)
• Les commandes viennent généralement avant que l'objet qu'il décrit. (I. e. si vous essayez de document d'une propriété, le commentaire doit venir avant l' @property de texte.) Ils peuvent venir par la suite, sur la même ligne, /*!<, /**<ou //!<.
• Vous pouvez ajouter de la documentation pour les classes, fonctions, propriétés et variables.
• Toutes ces commandes apparaissent en vert foncé texte pour signifier qu'ils sont des commandes valides, sauf pour @returns.
• Vous pouvez avoir besoin pour construire votre projet (ou redémarrez-le Xcode) avant les dernières modifications apportées à vos documents apparaissent.

Où voir la documentation:

1. Cours de code complet, vous verrez le bref texte:

Cela permettra de montrer le bref texte (sans formatage); si aucun texte bref existe, il affiche une concaténation de tout le texte jusqu'à la première @bloc; si aucune n'existe (par exemple, vous commencez avec @return), alors il sera concat tout le texte d'entrelacement de loin toutes les commandes@.

2. L'Option-clic sur un nom de l'identificateur:

3. Dans le Rapide de l'Aide de l'Inspecteur de panneau

(Voir la première capture d'écran.)

4. Dans Doxygen

Puisque les commandes dans Xcode 5 sont compatibles avec Doxygen, vous pouvez télécharger et utiliser Doxygen pour générer des fichiers de documentation.

D'Autres Notes

Pour une introduction générale à Doxygen et la manière de documenter le code Objective-C, cette page semble être une bonne ressource.

Des Descriptions de certaines commandes prises en charge:

• @brief: pour insérer du texte au début de la description du champ, et est le seul texte qui apparaîtra lors de la complétion de code.

Le suivant ne fonctionne pas:

• \n: ne pas générer un saut de ligne. Une façon de créer un saut de ligne est de s'assurer que rien n'est sur cette ligne. Pas même un seul caractère espace!
• \example

Les éléments suivants ne sont pas pris en charge (ils ne semblent même pas en vert foncé):

• \cite
• \docbookonly
• \enddocbookonly
• \endinternal
• \endrtfonly
• \endsecreflist
• \idlexcept
• \mscfile
• \refitem
• \relatedalso
• \rtfonly
• \secreflist
• \courte
• \extrait de
• \tableofcontents
• \vhdlflow
• \~
• \"
• .
• ::
• \|

Apple mots clés réservés:

Apple utilise ce qui semble être des mots réservés qui ne fonctionne que dans leur documentation. Bien qu'ils apparaissent en vert foncé, il paraît qu'on ne peut l'utiliser que fait Apple. Vous pouvez voir des exemples d'Apple, l'utilisation à des fichiers tels que des AVCaptureOutput.h.

Voici une liste de quelques-uns de ceux-ci:

• @abstrait, @disponibilité, @classe, @discussion, @deprecated, @méthode, @property, @protocole, @liées, @ref.

Au mieux, le mot clé sera la cause d'une nouvelle ligne dans le champ de Description (par exemple, @discussion). Au pire, le mot-clé et le texte qui suit, il n'apparaîtra pas dans l'aide rapide (par exemple, @classe).

Answer 2

Cela a changé dans Xcode 6 lorsque vous utilisez Swift .

Plus précisément, le format actuel est le suivant:

 /**
        Squares a number.

        :param: number The number to square.

        :returns: The number squared.
    */
 

Remarquez comment @param est maintenant :param: .

Vous pouvez également inclure des puces dans votre documentation:

 /**
        - square(5) = 25
        - square(10) = 100
    */
 

Answer 3

Sentimental:

Vous devrez peut-être créer votre projet avant que les dernières modifications apportées à votre documentation ne s'affichent.

Parfois, cela n'a pas été suffisant pour moi. Fermer Xcode et ouvrir le projet back up remédie généralement à ces cas.

J'obtiens aussi des résultats différents dans les fichiers .h et les fichiers .m. Je ne peux pas obtenir de nouvelles lignes lorsque les commentaires de documentation sont dans un fichier d'en-tête.