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 au doxygen, mais semble ne prendre en charge qu'un sous-ensemble de ces fonctionnalités .

Quelles commandes sont prises en charge et lesquelles ne le sont pas?
Certains de leurs usages diffèrent-ils du doxygène?

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 @bet les \bdeux 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 @propertytexte.) 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).

Swift 2.0 utilise la syntaxe suivante:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Remarquez comment @paramc'est maintenant - parameter.

Vous pouvez également désormais inclure des puces dans votre documentation:

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

Sensible:

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

Parfois, cela ne me suffit pas. La fermeture de Xcode et l'ouverture de la sauvegarde du projet remédient généralement à ces cas.

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

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 inclut, abstract, discussion, brief, pre, post, sa, see, availability,class , deprecated, method, property, protocol, related, ref.