Comment utiliser Swift commentaires de documentation
J'ai quelques questions sur Swift commentaires sur la documentation:
Existe-t-il un moyen de créer une section Déclarations associées comme certaines des documentations Apple a? Par exemple, lorsque je Option+Click la méthode
tablewView(_:heightForRowAtIndexPath:), elle me relie à trois autres méthodes connexes dans la documentation générée.Y a-t-il une étiquette d'avertissement dans Swift? Je sais que Objective-C m'a permis de faire
@warninget obtenez un avertissement en gras dans la documentation générée. Cependant,:warning:ne fait rien dans les commentaires de la documentation de Swift, donc j'étais curieux s'il y avait une autre façon.Existe-t-il un moyen de transformer ma documentation en un fichier HTML dont le format est similaire à celui de la documentation Apple? Je sais que dans d'autres IDE, comme Eclipse, je peux générer de la documentation HTML pour mon code. Est-ce que XCode a cela?
Vous pouvez utiliser balisage pour écrire des commentaires sur la documentation de la cour de récréation et du code.
- Pour une documentation riche sur les terrains de jeux, utilisez
//:ou/*: */. - Pour la documentation du code, utilisez
///ou/** */.
Exemple
/// This function returns a *hello* string for a given `subject`.
///
/// - Warning: The returned string is not localized.
///
/// Usage:
///
/// println(hello("Markdown")) // Hello, Markdown!
///
/// - Parameter subject: The subject to be welcomed.
///
/// - Returns: A hello string to the `subject`.
func hello(subject: String) -> String {
return "Hello, \(subject)!"
}
Réponses à vos questions
Non. Alors que il y a une balise de balisage
SeeAlso, ce n'est pas encore assez intelligent pour créer un lien vers des symboles associés dans votre bibliothèque ou dans une bibliothèque tierce.Oui, il y a une balise de balisage
Warning. Voir mon exemple ci-dessus.Même si Xcode peut générer une représentation XML des commentaires de la documentation , il ne peut pas produire de fichier HTML. Je recommande d'utiliser jazzy pour cela.
Xcode 7.0 beta 4
La notation a été modifiée (:param: ne fonctionne plus ...)
/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
return "Ouch. This is \(size) poo!"
}
Et cela ressemble à ceci:
Vous pouvez utiliser soit /// ou /** */
Pour ceux qui souhaitent l'ajouter en tant qu'extrait de code. Swift 5, XCode 11.3 +
Ceci est un ajout à: la réponse de Yogendra Singh dans ce fil
/**
<#Summay text for documentation#>
- parameter <#parameterName#>: <#Description#>.
- returns: <#Return values#>
- warning: <#Warning if any#>
# Notes: #
1. <#Notes if any#>
# Example #
```
// <#Example code if any#>
```
*/
Copiez et collez le code ci-dessus dans Xcode. Sélectionnez le code, puis cliquez avec le bouton droit.
Enregistrez l'extrait de code et donnez le nom d'achèvement comme documentation.
Maintenant, si nous commençons à taper la documentation , l'extrait sera affiché dans l'achèvement du code.
Utilisez la notation suivante pour les commentaires de documentation.
/**
This method sum two double numbers and returns.
Here is the discussion. This methods adds two double and return the optional Double.
- parameter number1: First Double Number.
- parameter number2: Second Double Number.
- returns: The sum of two double numbers.
# Notes: #
1. Parameters must be **double** type
2. Handle return type because it is optional.
# Example #
```
if let sum = self.add(number1: 23, number2: 34) {
print(sum)
}
```
*/
func add(number1: Double, number2: Double) -> Double? {
return number1 + number2
}
(3) Pour générer votre documentation en HTML (ou même générer des docsets), je recommande fortement jazzy qui a été construit à cet effet.
Même si c'est toujours WIP, cela fonctionne très bien et génère une documentation avec une présentation similaire à la Apple
Pour Swift code Apple a abandonné HeaderDoc et est passé à une syntaxe Markdown style . Ils ont choisi CommonMark variante de Markdown avec quelques Swift extensions de mots clés spécifiques.
Documentation des symboles
Il y a quatre sections, dont seule la description est toujours incluse:
- La description
- Paramètres
- Jette
- Retour
Après la description, l'ordre des autres sections n'a plus d'importance. Vous ne pouvez avoir qu'une seule section Throws et une seule section Returns.
/**
What does this function do?
Some discussion
- Parameters:
- firstParam: Describe the first param
- secondParam: Describe the second param
- Returns: true or false
- Throws: SomeError you might want to catch
*/
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
return true;
}
ou l'équivalent
/// What does this function do?
///
/// Some discussion
///
/// - Parameters:
/// - firstParam: Describe the first param
/// - secondParam: Describe the second param
/// - Returns: true or false
/// - Throws: SomeError you might want to catch
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
return true;
}
Si un commentaire de documentation commence par autre chose qu'un paragraphe, tout son contenu est mis dans la discussion.
Guide rapide des mots clés
Si vous voulez vous faire plaisir, il existe une longue liste de mots clés que vous pouvez inclure n'importe où dans la description.
- Attention:- Author:- Authors:- Bug:- Complexity:- Copyright:- Date:- experiment:- important:- invariant:- Note:- Precondition:- Postcondition:- Remark:- Requires:- seealso:- Since:- Todo:- Version:- Warning: etc.
Pour générer automatiquement un document, appuyez sur ⌘ command+⌥ option+/ ou Editor -> Structure -> Add Documentation. Ces commandes ajoutent /// au début de chaque nouvelle ligne. Vous pouvez également ajouter manuellement /** comme première ligne et */ à la dernière ligne de votre doc.