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:
///
/// 
///
/// - 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:
/// 
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
