Est-ce que Swift prend en charge la génération de documentation?
De nombreuses langues supportent les commentaires de la documentation permettant à un générateur (comme javadoc ou doxygen ) de générer de la documentation de code par analyse ce même code.
Est-ce que Swift possède une fonction de commentaire de type documentation comme celle-ci?
Les commentaires sur la documentation sont pris en charge de manière native dans Xcode, ce qui permet de produire une documentation intelligemment rendue dans l’aide rapide ⌥cliquer sur des symboles et dans l'inspecteur d'aide rapide ⌥⌘2).
Les commentaires de la documentation Symbol reposent désormais sur le même principe syntaxe de Markdown utilisé par les commentaires de terrains de jeux, de sorte que beaucoup de ce que vous pouvez faire dans les terrains de jeux 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 existe des différences entre la syntaxe des commentaires de terrain de jeu riches et la documentation des symboles; ceux-ci sont indiqués dans le document (par exemple, les guillemets ne peuvent être utilisés que dans des terrains de jeu).
Vous trouverez ci-dessous un exemple et une liste des éléments de syntaxe qui fonctionnent actuellement pour les commentaires de la documentation sur les symboles.
Mises à jour
Xcode 7 beta 4 ~ Ajouté "- Throws: ..." en tant qu'élément de liste de niveau supérieur qui apparaît à côté des paramètres et renvoie des descriptions dans Aide rapide.
Xcode 7 beta 1 ~ Quelques changements importants dans la syntaxe avec Swift 2 - les commentaires sur la documentation reposent désormais sur Markdown (comme les terrains de jeu).
Xcode 6.3 (6D570) ~ Le texte en retrait est maintenant formaté en tant que blocs de code, les indentations suivantes étant imbriquées. Il ne semble pas possible de laisser une ligne vide dans un tel bloc de code. Si vous tentez de le faire, le texte sera ajouté à la fin de la dernière ligne avec des caractères.
Xcode 6.3 beta ~ Du 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é sur Markdown )
Style de commentaire
Les commentaires de style /// (en ligne) et /** */ (bloc) sont pris en charge pour la production de commentaires dans la documentation. Bien que je préfère personnellement le style visuel de /** */ commentaires, l'indentation automatique de Xcode peut ruiner la mise en forme de ce style de commentaire lors du copier/coller, car elle supprime les blancs. 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 restituée sous forme de code:
/**
See sample usage:
let x = method(blah)
*/
Pour cette raison, j'utilise généralement /// et je l'utilise pour le reste des exemples de cette réponse.
Éléments de bloc
En-tête:
/// # My Heading
ou
/// My Heading
/// ==========
Sous-titre:
/// ## My Subheading
ou
/// My Subheading
/// -------------
Règle horizontale:
/// ---
Listes non ordonnées (à puces):
/// - An item
/// - Another item
Vous pouvez également utiliser + ou * pour les listes non ordonnées, il faut simplement que ce soit 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)
/// }
Un retrait d'au moins quatre espaces est requis.
Éléments en ligne
Caractères italiques:
/// 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:
/// 
L'URL peut être une URL Web (en utilisant "http: //") ou une URL de chemin de fichier absolu (je n'arrive pas à obtenir le fonctionnement des 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 dans un seul emplacement gérable:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Mots clés
Outre la mise en forme Markdown, Xcode reconnaît que d'autres mots-clés de balisage doivent être affichés en évidence dans l'aide rapide. Ces mots-clés de balisage prennent principalement le format - <keyword>: (à l'exception de parameter, qui inclut également le nom du paramètre situé avant les deux points), le mot-clé lui-même pouvant être écrit avec n'importe quelle combinaison de caractères majuscules/minuscules.
Mots-clés de la section de symboles
Les mots-clés suivants sont affichés en tant que sections importantes dans la visionneuse d'aide, sous la section "Description" et au-dessus de la section "Déclaré dans". Lorsqu'ils sont inclus, leur ordre est corrigé comme indiqué ci-dessous, même si vous pouvez les inclure dans l'ordre de votre choix.
Voir la liste entièrement documentée des mots-clés de section et leurs utilisations prévues dans la section section Commands de symboles 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 suivante de mots-clés est affichée en tant que titres 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 pour le reste de la section "Description".
Liste complète paraphrasée depuis cet excellent article de blog par Erica Sadun. Reportez-vous également à la liste entièrement documentée des mots-clés et de leurs utilisations prévues dans la section section Commandes de champs de description de symbole de la référence de formatage de balisage . .
Attributions:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Disponibilité:
/// - since:
/// - version:
Admonitions:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Etat 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 à code source ouvert.
$ [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 sur NSHipster
Voici quelques éléments qui permettent de documenter le code Swift 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";
}
}
Les informations ci-dessus sont rendues dans l'aide rapide comme vous le souhaitiez avec des listes numériques formatées, des puces, des paramètres et une documentation sur les valeurs renvoyées.
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 une documentation" dans le menu "Editeur" 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 le traitement des commentaires "///" (bien que probablement pas encore tout).
Ecrire quelque chose comme:
/// Hey!
func bof(a: Int) {
}
Ensuite, cliquez sur le nom de la fonction avec une option 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 avec l'équivalent Obj-C)
Objective-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 utilisez uniquement Swift, alors Jazzy est intéressant à regarder.
J'ai trouvé quelque chose d'intéressant, en fouillant dans le binaire Xcode. Fichiers avec la fin .swiftdoc. Il possède certainement des documents, car ces fichiers contiennent les documents de l'API Swift UIKit/Foundation. Malheureusement, il semble qu'il s'agisse d'un format de fichier propriétaire, à utiliser dans l'afficheur de documentation dans Xcode.
Dans l'éditeur Xcode -> Structure -> Ajouter de la documentation.
