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?

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."
}

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

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.

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#>

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à :)

Je peux confirmer que ShakenManChild a fourni une solution peopr

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

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#>.
*/

Si vous n'utilisez que Swift, Jazzy mérite d'être étudié.

https://github.com/realm/jazzy

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.

Dans Xcode Editor -> Structure -> Add Documentation.

Jazzy peut aider à générer une belle documentation de style pomme. Voici un exemple d'application avec des détails sur la façon d'utiliser et de configurer rapidement.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

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.

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

La source