Swift prend-il en charge la génération de documentation?

238

De nombreuses langues prennent en charge les commentaires de documentation pour permettre à un générateur (comme javadocou doxygen ) de générer de la documentation de code en analysant ce même code.

Swift a-t-il une fonctionnalité de commentaire de documentation de type comme celle-ci?

pconcepcion
la source
Sachant que Xcode avec objective-c permet des commentaires de documentation, je pense qu'Apple ajoutera cette option à Xcode avec swift dans un avenir proche (cependant, ce n'est qu'une supposition, je n'ai aucune preuve)
Garoal
@ Δdeveloper Je supposais la même chose, mais comme je n'ai vu aucune référence, je me demandais si quelqu'un pouvait le confirmer et aussi s'il y aurait un outil de documentation spécifique.
pconcepcion
1
Ils ajouteront certainement quelque chose à l'avenir, le // MARK:commentaire est également prévu pour une future version de Xcode.
Leandros
Commentaires sur le style oxygène type de travail pour les méthodes de classe, avec ~ plusieurs ~ BEAUCOUP DE mises en garde. Pour ma part, je continuerai à utiliser le style Doxygen (comme je l'ai fait pour Obj-C) et j'espère que Xcode améliorera son support pour ceux-ci.
Pascal
1
Pour la documentation des paramètres de bloc, voir stackoverflow.com/a/41970146/1054573
Leonard Pauli

Réponses:

386

Les commentaires de documentation sont pris en charge nativement dans Xcode, produisant une documentation intelligemment rendue dans l'aide rapide (à la fois dans la fenêtre contextuelle lors du clic sur les symboles et dans l'inspecteur d'aide rapide ⌥⌘2).

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

Pour plus de détails sur la syntaxe, voir Référence de formatage de balisage . Notez qu'il y a quelques divergences entre la syntaxe des commentaires riches de la cour de récréation et la documentation des symboles; ceux-ci sont indiqués dans le document (par exemple, les guillemets ne peuvent être utilisés que dans les terrains de jeux).

Voici un exemple et une liste des éléments de syntaxe qui fonctionnent actuellement pour les commentaires de documentation des symboles.


Mises à jour

Xcode 7 beta 4 ~ " - Throws: ..." ajouté en tant qu'élément de liste de niveau supérieur qui apparaît à côté des paramètres et des descriptions de retour dans l'aide rapide.

Xcode 7 beta 1 ~ Quelques changements importants de syntaxe avec Swift 2 - commentaires de documentation désormais basés sur Markdown (comme pour les terrains de jeux).

Xcode 6.3 (6D570) ~ Le texte en retrait est désormais formaté en blocs de code, les retraits suivants étant imbriqués. Il ne semble pas possible de laisser une ligne vierge dans un tel bloc de code - en essayant de le faire, le texte sera collé à la fin de la dernière ligne avec des caractères.

Xcode 6.3 beta ~ Le code en ligne peut maintenant être ajouté aux commentaires de documentation à l'aide de 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 -> String {
    if unlucky { throw Error.BadLuck }
    return "Totally contrived."
}

Aide rapide sur la documentation Swift


Syntaxe pour Swift 2 (basée sur Markdown )


Style de commentaire

Les commentaires de style ///(en ligne) et /** */(bloc) sont pris en charge pour produire des commentaires de documentation. Bien que je préfère personnellement le style visuel des /** */commentaires, l'indentation automatique de Xcode peut ruiner la mise en forme de ce style de commentaire lors de la copie / du collage car elle supprime les espaces principaux. Par exemple:

/**
See sample usage:

    let x = method(blah)
*/

Lors du collage, l'indentation du bloc de code est supprimée et n'est plus rendue sous forme de code:

/**
See sample usage:

let x = method(blah)
*/

Pour cette raison, j'utilise généralement ///, et je vais l'utiliser pour le reste 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 des 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 requise.


Éléments en ligne

Souligné (italique):

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


Fort (gras):

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

Notez que vous ne pouvez pas mélanger des astérisques ( *) et des 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 (en utilisant "http: //") ou une URL de chemin de fichier absolu (je n'arrive pas à faire fonctionner les chemins de fichier relatifs).

Les URL des liens et des images peuvent également être séparées de l'élément en ligne afin de conserver toutes les URL en un seul endroit gérable:

/// 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 d'autres mots clés de balisage à afficher en évidence dans l'aide rapide. Ces mots-clés de balisage prennent principalement le format - <keyword>:(à l'exception parameter, qui inclut également le nom du paramètre avant les deux-points), où le mot-clé lui-même peut être écrit avec n'importe quelle combinaison de caractères majuscules / minuscules.

Mots-clés de la section des symboles

Les mots clés suivants sont affichés sous forme de sections bien visibles dans la visionneuse d'aide, sous la section "Description" et au-dessus de la section "Déclaré dans". Une fois inclus, leur commande est fixée comme indiqué ci-dessous, même si vous pouvez les inclure dans l'ordre que vous souhaitez dans vos commentaires.

Consultez la liste entièrement documentée des mots-clés de section et de leurs utilisations prévues dans la section Commandes de section de symbole de la référence de formatage de balisage .

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

Alternativement, vous pouvez écrire chaque paramètre de cette façon:

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

Symbole Description Mots clés du champ

La liste de mots clés suivante s'affiche sous forme de titres en gras dans le corps de la section "Description" de la visionneuse d'aide. Ils apparaîtront dans l'ordre dans lequel vous les écrivez, comme dans le reste de la section "Description".

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 de description du symbole de la référence de mise en forme des balises .

Attributions:

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

Disponibilité:

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

Admonitions:

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

État de développement:

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

Qualités de mise en œuvre:

/// - 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 tiré de cet article NSHipster

Stuart
la source
1
On dirait que le comportement a changé dans la version finale de Xcode 6.3 (6D570). Les blocs en retrait sont désormais formatés en blocs de code et peuvent être imbriqués avec plus de deux niveaux.
NexD.
2
Très belle description de la syntaxe de la documentation Swift 2.0. Vous devez mettre à jour le message pour inclure le/// - todo: keyword
Leonardo
2
@uchuugaka En fait non. Il peut avoir été basé sur reStructuredText auparavant, mais à partir de la documentation de Xcode 7, les commentaires sont basés sur Markdown, avec le même format de base que les commentaires sur les terrains de jeux. Voir les notes de publication de Xcode 7 pour plus de détails.
Stuart
2
Existe-t-il un moyen de créer un lien vers d'autres fonctions dans le même fichier, comme JavaDoc? Par exemple, "voir myOtherMethod(param1:)pour des fonctionnalités étendues"
Ben Leggiero
1
@BenLeggiero, oui, en utilisant /// - Tag: otherMethodet [otherMethod](x-source-tag://otherMethod). Pour plus de détails, voir ma réponse .
Clay Ellis
58

Voici quelques éléments qui fonctionnent pour documenter du code rapide dans Xcode 6. Il est très bogué 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 : String) -> String {
        return "Did the \(name) thing";
    }
}

Ce qui précède est rendu dans l'aide rapide comme vous vous en doutez avec les listes numériques formatées, les puces, la documentation des paramètres et des valeurs de retour.

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

ShakenManChild
la source
2
Mattt Thompson a écrit un article à ce sujet , et il pense que c'est le cas reStructuredText.
Eonil
Dans l'exemple ci-dessus, les symboles plus (+) et moins (-) agiront également comme des puces, en plus des astérisques indiqués.
Vince O'Sullivan,
Il semble qu'une ///ligne de commentaire ( ) vide soit requise entre tout texte explicatif et les lignes :param:ou :returns:. Si vous omettez cela, XCode (6.1.1 au moment de la rédaction) inclut l'aide des paramètres dans le corps principal de la description de la fonction.
Robin Macharg
Malheureusement, cela ne fonctionne pas avec Xcode 7 Beta. J'espère qu'ils le corrigeront dans une version finale.
stevo.mit
1
Xcode 7 a adopté une syntaxe différente: ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7
Zmey
41

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

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

Appuyez ensuite sur command+ option+/ ou choisissez "Structure" - "Ajouter de la documentation" dans le menu "Editeur" de Xcode, et il générera pour vous le modèle de commentaires suivant:

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>
Logan Jahnke
la source
Merci pour cela. Je mentionnerai simplement que le raccourci clavier que vous indiquez ne semble pas fonctionner sur un clavier danois, où "/" est shift- "7".
RenniePet
27

Swift inclut la gestion des commentaires "///" (bien que ce ne soit probablement pas encore tout).

Écrivez quelque chose comme:

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

}

Ensuite, cliquez sur le nom de la fonction et voilà :)

Jean Le Moignan
la source
11

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

DAH
la source
8

Oui. Base commune (j'ai fait des extraits pour cela avec un é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#>.
*/
Jakub Truhlář
la source
6

J'ai trouvé quelque chose d'intéressant, en creusant dans le binaire Xcode. Fichiers avec la fin .swiftdoc. Il contient certainement des documents, car ces fichiers contiennent les documents de l'API Swift UIKit / Foundation, malheureusement il semble que ce soit un format de fichier propriétaire, à utiliser dans la visionneuse de documentation dans Xcode.

Leandros
la source
5

Dans Xcode Editor -> Structure -> Add Documentation.

entrez la description de l'image ici

Abo3atef
la source
Oui, il a été mentionné il y a plus de 3 mois par Logan Jahnke .
Franklin Yu
-1

C'est peut-être une bonne idée d'avoir un œil sur AppleDoc ou sur le propre HeaderDoc d' Apple qui n'est pas très reconnu. Je peux toujours trouver quelques astuces HeaderDoc dans le terminal 10.9 Mavericks (headerdoc2html)

Je recommande de lire la dernière " Quoi de neuf dans Xcode " * (je ne sais pas si c'est toujours sous NDA) * Le lien pointe vers la version Xcode 5.1 qui contient aussi des informations sur HeaderDoc.

TiBooX
la source
-1

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

La source

Matt Zanchelli
la source
1
Eh bien, je posais des questions sur Swift dans ce cas.
pconcepcion
@pconcepcion Utilisez-vous Swift dans Xcode? Alors oui.
Matt Zanchelli
1
Matt, d'après ce que je sais (je peux me tromper) Swift, il n'est pas pris en charge jusqu'à la version bêta de Xcode 6, donc je ne suis pas sûr si la documentation pour Xcode 5 est valide pour Xcode 6 (et pour Swift ensuite)
pconcepcion
@pconcepcion Cela fonctionne. J'ai utilisé la même documentation doxygen que celle utilisée dans Objective-C et cela fonctionne. Au-dessus d'une méthode ou d'une propriété, j'utilise /// This is what the method does.etc.
Matt Zanchelli
Ok, alors le problème est que vous l'avez testé sur Xcode 6. J'étais confus parce que vous parliez de Xcode 5 et le lien est pour Xcode 5
pconcepcion