web-dev-qa-db-fra.com

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

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?
Certains de leurs usages diffèrent-ils du doxygen?

objective-cdocumentationcommentsdoxygenxcode5
185
Senseful

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

enter image description here

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

Notes:

  • Les commandes doivent être dans un /** block */, /*! block */ ou préfixé par /// ou //!.
  • Les commandes fonctionnent avec le @ _ ( headerdoc style) ou le \ _ ( doxygen style) préfixe. (C'est à dire. @b et \b les deux font la même chose.)
  • Les commandes viennent généralement avant l’article qu’elles décrivent. (Ie, si vous essayez de documenter une propriété, le commentaire doit venir avant le @property texte.) Ils peuvent venir après, sur la même ligne, avec /*!<, /**<, //!<, ///<.
  • Vous pouvez ajouter de la documentation à 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 apparaissent.

Où voir la documentation:

1. Une fois le code terminé, vous verrez le texte bref:

enter image description here

Cela montrera le texte bref (sans mise en forme); si aucun texte bref n'existe, il affichera une concaténation de tout le texte jusqu'au premier bloc @; s'il n'en existe pas (par exemple, vous commencez par @retour), alors le texte sera séparé de toutes les commandes @.

2. Option-cliquant sur un nom d'identifiant:

enter image description here

3. Dans le panneau Inspecteur d'aide rapide

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

4. Dans Doxygen

Les commandes de Xcode 5 étant 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 à la documentation du code Objective-C, cette page semble être une bonne ressource.

Descriptions de certaines des commandes prises en charge:

  • @brief : insère du texte au début du champ de description et est le seul texte qui apparaîtra pendant la complétion du code.

Ce qui suit ne fonctionne 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 n’est 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
  • \ endecreflist
  • \ idlexcept
  • \ mscfile
  • \ refitem
  • \ relatedalso
  • \ rtf uniquement
  • \ secreflist
  • \court
  • \fragment
  • \table des matières
  • \ vhdlflow
  • \ ~
  • \ "
  • .
  • ::
  • \ |

Mots-clés réservés Apple:

Apple utilise des mots clés apparemment 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. 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). Dans le pire des cas, le mot-clé et le texte qui le suit ne figureront pas dans l'aide rapide (par exemple, @class).

416
Senseful

Swift 2. utilise la syntaxe suivante:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Remarquez comment @param est maintenant - parameter.

Vous pouvez également maintenant inclure des puces dans votre documentation:

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

Senseful:

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

Parfois, cela n'a pas suffi pour moi. Fermer Xcode et ouvrir la sauvegarde du projet corrigent généralement ces cas.

J'obtiens également 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 la documentation sont dans un fichier d'en-tête.

9
weezma2004

La plupart du formatage a changé pour Swift 2.0 (à partir de Xcode7 ß3, également vrai dans ß4)

au lieu de :param: thing description of thing (comme dans Swift 1.2)

c'est maintenant - parameter thing: description of thing

La plupart des mots-clés ont été remplacés par - [keyword]: [description] au lieu de :[keyword]: [description]. Actuellement, la liste des mots-clés qui ne fonctionnent pas comprend: abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.

5
mittens