Si vous vous posez des questions sur la documentation, je vous suggère de consulter Jazzy, un outil pour générer de la documentation à partir de vos commentaires de code en ligne. C'est une bonne façon de créer une documentation autonome à partir de vos commentaires de code et cela est cohérent avec les conventions d'Apple.
La convention de base utilisée est la suivante. Imaginons que vous avez une classe définie comme suit:
/// Some incredibly useful class
public class MyClass {
/// Performs some foo-like operation
///
/// - Parameter bar: The bar parameter.
public class func foo(_ bar: String) {
// do something
}
/// Some bazzy operation
///
/// - Parameter qux: The bar parameter.
public func baz(_ quz: String) {
// do something
}
}
volonté Jazzy génère une documentation qui ressemble à:
Remarque, il est juste de vous montrer les étiquettes argument. Si vous appuyez sur un, il vous montre que ce soit une méthode de type et ce que les noms de paramètres sont les suivants:
Dans la question initiale, il n'a pas été clair, vous parliez de la documentation, je discuté des conventions que l'on rencontre dans le code. Cette réponse est ci-dessous.
Dans Swift, il est . pour les deux types d'instances et de propriété. C'est juste une question de ce qui précède .. S'il s'agit d'un type, c'est une propriété/méthode type. Considérez:
let b = Foo.bar
Ce fait référence à la propriété de type bar pour le type Foo. Mais si ce qui précède . est une instance d'un type, alors vous avez affaire à une propriété/méthode d'instance.Tenir compte:
let b = Baz()
let q = baz.qux
Dans ce cas, qux fait référence à une propriété d'instance de Baz, parce b une instance du type Baz.
Au risque de brouiller les cartes, une mise en garde au schéma ci-dessus est l'utilisation des « sélectionneurs » (un motif Objective-C plus) à Swift. Dans ce cas, le choix de target indique ce que les références selector. Si vous fournissez une instance pour target, le selector fait référence à une méthode d'instance. Si vous fournissez un type pour le target, le selector fait référence à une méthode de type. Ainsi, dans cet exemple, le selector fait référence à une méthode d'instance:
Timer.scheduledTimer(timeInterval: 1, target: self, selector: #selector(ViewController.foo), userInfo: nil, repeats: false)
Alors que le suivant appellera une méthode de type:
Timer.scheduledTimer(timeInterval: 1, target: ViewController.self, selector: #selector(ViewController.foo), userInfo: nil, repeats: false)
Note, dans les deux ces deux exemples, si nous sommes interagissant au sein d'une même classe, nous omettons généralement le nom de la classe. Vous devez seulement référencer explicitement le type si c'est dans une autre classe. Mais j'inclus ce motif target/selector simplement parce qu'il montre une autre syntaxe, légèrement différente, de la syntaxe Class.method.
Mais cette exception est unique. Le modèle général est xxx.yyy où si xxx est une instance d'un type, alors yyy est une propriété/méthode d'instance, alors que si xxx est le nom d'un type, alors yyy est une propriété de type/méthode.
Les références de append(_ newElement:) comme append(_:) est tout autre chose. C'est juste un cas où le premier paramètre, newElement n'a pas d'étiquette externe, donc il est appelé sans étiquette, par ex. array.append(object). Donc, append(_:) est juste une notation qui vous montre comment ça s'appelle (où nous ne nous soucions pas du nom du paramètre interne), mais append(_ newElement:) est comment il est mis en œuvre (où nous voulons savoir comment se référer à ce paramètre dans la méthode) .
Eh bien, ce ne fut pas la réponse que je cherchais, mais je vous remercie pour la leçon de toute façon. :-) Je m'interroge sur la notation à des fins de documentation. J'ai mis à jour ma question pour le rendre plus clair. – ma11hew28