Swift a-t-il un support pour la génération de documentation?

De nombreux langages prennent en charge les commentaires de documentation pour permettre à un générateur (comme javadoc ou doxygen ) de générer une documentation de code en analysant ce même code.

Est-ce que Swift a une fonctionnalité de commentaire de type documentation comme celle-ci?

Les commentaires sur la documentation sont pris en charge en mode natif dans Xcode, produisant une documentation intelligemment rendue dans l’aide rapide (à la fois dans le pop-up lors du icking -clic de symboles et dans l’inspecteur d’aide rapide ⌥⌘2 ).

Les commentaires de la documentation sur les symboles sont désormais basés sur la même syntaxe de Markdown utilisée par les commentaires sur les terrains de jeux, de sorte que beaucoup de ce que vous pouvez faire dans les terrains de jeux peut maintenant être utilisé directement dans la documentation du code source.

Pour plus de détails sur la syntaxe, voir Référence de mise en forme de balisage . Notez qu’il existe des divergences entre la syntaxe des commentaires enrichis et la documentation des symboles; ceux-ci sont indiqués dans le document (par exemple, les citations ne peuvent être utilisées que dans les terrains de jeux).

Vous trouverez ci-dessous un exemple et une liste des éléments de syntaxe qui fonctionnent actuellement pour les commentaires de documentation de symboles.


Mises à jour

Xcode 7 beta 4 ~ Ajout de ” - Throws: ... ” comme élément de liste de niveau supérieur qui apparaît à côté des parameters et renvoie les descriptions dans l’aide rapide.

Xcode 7 beta 1 ~ Quelques modifications importantes de la syntaxe avec Swift 2 – commentaires sur la documentation désormais basés sur Markdown (identique aux terrains de jeux).

Xcode 6.3 (6D570) ~ Le texte en retrait est maintenant formaté en blocs de code, les indentations suivantes étant nestedes. Il ne semble pas possible de laisser une ligne vide dans un tel bloc de code – en essayant de le faire, le texte est ajouté à la fin de la dernière ligne avec tous les caractères.

Xcode 6.3 beta ~ Le code Inline peut maintenant être ajouté aux commentaires de la documentation en utilisant des backticks.


Exemple pour Swift 2

 /// Text like this appears in "Description". /// /// Leave a blank line to separate further text into paragraphs. /// /// You can use bulleted lists (use `-`, `+` or `*`): /// /// - Text can be _emphasised_ /// - Or **strong** /// /// Or numbered lists: /// /// 7. The numbers you use make no difference /// 0. The list will still be ordered, starting from 1 /// 5. But be sensible and just use 1, 2, 3 etc… /// /// --- /// /// More Stuff /// ========== /// /// Code /// ---- /// /// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage: /// /// // Create an integer, and do nothing with it /// let myInt = 42 /// doNothing(myInt) /// /// // Also notice that code blocks scroll horizontally instead of wrapping. /// /// Links & Images /// -------------- /// /// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images: /// /// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language") /// /// - note: That "Note:" is written in bold. /// - requires: A basic understanding of Markdown. /// - seealso: `Error`, for a description of the errors that can be thrown. /// /// - parameters: /// - int: A pointless `Int` parameter. /// - bool: This `Bool` isn't used, but its default value is `false` anyway… /// - throws: A `BadLuck` error, if you're unlucky. /// - returns: Nothing useful. func doNothing(int: Int, bool: Bool = false) throws -> Ssortingng { if unlucky { throw Error.BadLuck } return "Totally consortingved." } 

Aide rapide sur la documentation Swift


Syntaxe pour Swift 2 (basé sur Markdown )

Style de commentaire

Les commentaires de style /// (inline) et /** */ (block) sont pris en charge pour la production de commentaires de documentation. Bien que je préfère personnellement le style visuel de /** */ comments, l’indentation automatique de Xcode peut gâcher le formatage pour ce style de commentaire lors de la copie / collage car il supprime les espaces blancs. Par exemple:

 /** See sample usage: let x = method(blah) */ 

Lors du collage, l’indentation du bloc de code est supprimée et il n’est plus traduit sous forme de code:

 /** See sample usage: let x = method(blah) */ 

Pour cette raison, j’utilise généralement /// et l’utilisera pour le rest des exemples de cette réponse.

Éléments de bloc

Titre:

 /// # My Heading 

ou

 /// My Heading /// ========== 

Sous-titre:

 /// ## My Subheading 

ou

 /// My Subheading /// ------------- 

La règle horizontale:

 /// --- 

Listes non classées (à puces):

 /// - An item /// - Another item 

Vous pouvez également utiliser + ou * pour les listes non ordonnées, il doit simplement être cohérent.

Listes ordonnées (numérotées):

 /// 1. Item 1 /// 2. Item 2 /// 3. Item 3 

Blocs de code:

 /// for item in array { /// print(item) /// } 

Une indentation d’au moins quatre espaces est requirejse.

Éléments en ligne

Emphase (italique):

 /// Add like *this*, or like _this_. 

Fort (gras):

 /// You can **really** make text __strong__. 

Notez que vous ne pouvez pas mélanger les astérisques ( * ) et les traits de soulignement ( _ ) sur le même élément.

Code en ligne:

 /// Call `exampleMethod(_:)` to demonstrate inline code. 

Liens:

 /// [Link Text](https://en.wikipedia.org/wiki/Hyperlink) 

Images:

 /// ![Alt Text](http://www.example.com/alt-image.jpg) 

L’URL peut être une URL Web (à l’aide de “http: //”) ou une URL de chemin d’access absolue (je n’arrive pas à obtenir des chemins de fichiers relatifs).

Les URL des liens et des images peuvent également être séparées de l’élément inline afin de conserver toutes les URL à un seul endroit:

 /// A [link][1] an an ![image][2] /// /// ... /// /// [1]: http://www.example.com /// [2]: http://www.example.com/image.jpg 

Mots clés

En plus du formatage Markdown, Xcode reconnaît les autres mots-clés de balisage à afficher de manière visible dans l’aide rapide. Ces mots-clés de balisage prennent principalement le format - : (l’exception est le parameter , qui inclut également le nom du paramètre avant les deux-points), où le mot-clé peut être écrit avec n’importe quelle combinaison de majuscules / minuscules.

Mots-clés de la section symbole

Les mots-clés suivants s’affichent sous forme de sections visibles dans le visualiseur d’aide, sous la section “Description” et au-dessus de la section “Déclarés dans”. Lorsqu’elles sont incluses, leur commande est corrigée comme indiqué ci-dessous, même si vous pouvez les inclure dans l’ordre de votre choix dans vos commentaires.

Reportez-vous à la liste complète des mots-clés de section et à leurs utilisations prévues dans la section Commandes de la section des symboles de la référence de mise en forme des annotations .

 /// - parameters: /// - < #parameter name#>: /// - < #parameter name#>: /// - throws: /// - returns: 

Vous pouvez également écrire chaque paramètre de la manière suivante:

 /// - parameter < #parameter name#>: 

Symbole Description Champ mots-clés

La liste de mots-clés suivante est affichée en gras dans le corps de la section “Description” du visualiseur d’aide. Ils apparaîtront dans l’ordre dans lequel vous les écrivez, comme dans le rest de la section “Description”.

La liste complète paraphrasée de cet excellent article de blog d’Erica Sadun. Consultez également la liste complète des mots-clés et leurs utilisations prévues dans la section Commandes du champ Description du symbole de la référence de formatage des annotations .

Atsortingbutions:

 /// - author: /// - authors: /// - copyright: /// - date: 

Disponibilité:

 /// - since: /// - version: 

Admonitions:

 /// - attention: /// - important: /// - note: /// - remark: /// - warning: 

État de développement:

 /// - bug: /// - todo: /// - experiment: 

Qualités d’implémentation:

 /// - complexity: 

Sémantique fonctionnelle:

 /// - precondition: /// - postcondition: /// - requires: /// - invariant: 

Références croisées:

 /// - seealso: 

Exportation de documentation

La documentation HTML (conçue pour imiter la propre documentation d’Apple) peut être générée à partir de la documentation en ligne à l’aide de Jazzy , un utilitaire de ligne de commande open-source.

 $ [sudo] gem install jazzy $ jazzy Running xcodebuild Parsing ... building site jam out ♪♫ to your fresh new docs in `docs` 

Exemple de console extrait de cet article de NSHipster

Voici quelques choses qui fonctionnent pour documenter le code rapide dans Xcode 6. Il est très buggé et sensible aux deux-points, mais c’est mieux que rien:

 class Foo { /// This method does things. /// Here are the steps you should follow to use this method /// /// 1. Prepare your thing /// 2. Tell all your friends about the thing. /// 3. Call this method to do the thing. /// /// Here are some bullet points to remember /// /// * Do it right /// * Do it now /// * Don't run with scissors (unless it's tuesday) /// /// :param: name The name of the thing you want to do /// :returns: a message telling you we did the thing func doThing(name : Ssortingng) -> Ssortingng { return "Did the \(name) thing"; } } 

Le contenu ci-dessus est affiché dans l’aide rapide, comme on peut s’y attendre avec des listes numériques formatées, des puces, une documentation sur les parameters et les valeurs de retour.

Rien de tout cela n’est documenté – déposez un radar pour les aider.

Nouveau dans Xcode 8 , vous pouvez sélectionner une méthode comme celle-ci

 func foo(bar: Int) -> Ssortingng { ... } 

Ensuite, appuyez sur command + option + / ou choisissez “Structure” – “Ajouter une documentation” dans le menu “Éditeur” de Xcode, et il générera le modèle de commentaires suivant pour vous:

 /// < #Description#> /// /// - parameter bar: < #bar description#> /// /// - returns: < #return value description#> 

Swift inclut “///” la gestion des commentaires (mais probablement pas tout).

Écrivez quelque chose comme:

 /// Hey! func bof(a: Int) { } 

Ensuite, cliquez sur le nom du func et cliquez dessus 🙂

Je peux confirmer que ShakenManChild a fourni une solution peopr

Assurez-vous simplement que vous avez une ligne vide sous la description!

Une situation invalide

Bonne façon

Autrement

Un autre style de commentaire

Si vous n’utilisez que Swift, Jazzy est intéressant.

https://github.com/realm/jazzy

Oui. Base commune (j’ai créé des extraits avec l’équivalent Obj-C)

Objectif c:

 /** @brief < #Short description - what it is doing#> @discussion < #Description#> @param < #paramName#> < #Description#>. @return < #dataType#> < #Description#>. */ 

Rapide

 /** < #Short inline description - what it is doing#> < #Description#> :param: < #paramName#> < #Description#>. :returns: < #dataType#> < #Description#>. */ 

J’ai trouvé quelque chose d’intéressant en creusant dans le binary Xcode. Fichiers avec la terminaison .swiftdoc . Il a définitivement docs, car ces fichiers contiennent les docs de l’API Swift UIKit / Foundation, malheureusement, il semble que ce soit un format de fichier propriétaire, utilisable dans la visionneuse de documentation de Xcode.

Dans Xcode Editor -> Structure -> Add Documentation.

entrer la description de l'image ici

Peut-être est-ce une bonne idée d’avoir un oeil sur AppleDoc ou le propre HeaderDoc d’ Apple qui n’est pas très reconnu. Je peux encore trouver des indices HeaderDoc dans le terminal 10.9 Mavericks (headerdoc2html)

Je recommande de lire le dernier ” Quoi de neuf dans Xcode ” * (pas sûr que ce soit toujours sous NDA) * Le lien pointe vers la version Xcode 5.1 qui contient des informations sur HeaderDoc aussi.

À partir de Xcode 5.0, les commentaires structurés Doxygen et HeaderDoc sont pris en charge.

La source