• 30 heures
  • Moyenne

Ce cours est visible gratuitement en ligne.

Ce cours est en vidéo.

Vous pouvez obtenir un certificat de réussite à l'issue de ce cours.

J'ai tout compris !

La documentation

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

Ok c'est cool, on trouve plein d'outils partout pour programmer.

'Y a pas un endroit où on peut tout trouver d'un coup?

Mmmmh pas vraiment. On peut trouver tous les outils natifs du Swift documenté dès sa naissance. C'est la documentation d'Apple qui, pour le moment, est très complète. Mais il existe tellement d'outils tiers que c'est impossible de tout recenser au même endroit.

La documentation d'Apple

Je vous l'ai dit, le Swift devient OpenSource, donc une nouvelle documentation fera place à celle d'Apple. Pour le moment, c'est la documentation d'Apple qui nous intéresse.

Comme un exemple est beaucoup plus parlant que du blabla, voici un extrait de la documentation sur la classe UIButton

Tout d'abord, le Swift est l'évolution de l'Objective-C. Vous pouvez donc choisir votre langage en haut à droite :

 

Nous, on clique sur Swift.

Ensuite, rendez-vous dans la partie haute de la page :

 

Voici quelques explications des différentes zones que vous voyez ici :

  • Inherits from = hérite de. Vous constaterez que la plupart des éléments graphiques héritent de UIView.

  • Conforms To = Se conforme à. Liste tous les protocoles auxquels se conforme notre UIButton.

  • Import Statement liste ce que vous devez importer pour utiliser le UIButton. Ici : UIKit.

  • Availability précise à partir de quelle version d'iOS vous pouvez utiliser cet élément.

En-dessous de cet en-tête, vous avez une (plus ou moins) courte description de l'objet considéré et enfin, des indications d'utilisation.

Par exemple, vous retrouvez l'utilisation classique d'une méthode qui répond au clic d'un bouton :

Suivie, à nouveau, de conseils d'utilisation.

Et, finalement, on retrouve les attributs et méthodes du bouton.

Mais, il en manque ?? C'est où background color ?

Background color est un attribut propre à UIView. La documentation ne réécrit pas tous les attributs des classes parentes.

Faites défiler encore et vous arrivez au niveau des méthodes. Cliquez sur une méthode pour obtenir des informations relatives à celle-ci. Cliquez par exemple sur setTitle(_:forState:).

Vous voyez immédiatement à quoi servent les paramètres et les usages : vous savez par exemple que si vous utilisez pour un même bouton un "titl" et un "attributed title", le bouton n'utilisera que l'"attributed title".

N'hésitez pas à utiliser la doc, c'est une mine d'infos précieuses.

Documentez votre code

Pour quoi faire ?

Si vous travaillez sur un gros projet, il est possible que vous ne soyez pas le seul à travailler dessus ; ou encore que vous ayez des troubles de la mémoire. Documenter votre code permet, en un clic, de savoir à quoi servent les méthodes, les classes, etc.

Par exemple, faites un cmd + clic sur numberOfSectionsInTableView dans votre classe Paramètres. Regardez le volet de droite, vous voyez la documentation de la méthode et vous savez immédiatement à quoi elle sert. (Si le volet de droite n'est pas visible, cliquez sur  ).

Comment l'écrire ?

On va créer une méthode qui va nous servir d'exemple. Rendez-vous dans "Exercice".

On va créer une méthode qui retourne le texte de la popup en fonction du score entré.

func textForAnswer(ans : Int) -> String {
    if ans == calcul.reponse {
        return "Bravo ! C'est une bonne réponse !!"
    } else {
        return "Non... Là, ça va vraiment pas..."
    }
}

On pourrait donc donner une description à la méthode, pour les paramètres et pour la valeur de retour.

Pour documenter, on a deux options : les commentaires "2 étoiles" ou "3 slashs".

Pour écrire une simple description, écrivez simplement du texte avant la méthode comme cela :

/**
Description de la méthode

*/

Pour donner des informations sur un paramètre :

/**
Description de la méthode

- Parameter ans: The answer given by the user cast as an integer
- Parameter unAutreParametre: Une autre description
*/

Pour donner des informations sur la valeur de retour :

/**

Function that will return the text to show to the user according to his answer

- Parameter ans: The answer given by the user cast as an integer

- returns: The text to show to the user
*/

Pour écrire un mot en gras, on l'encadre à l'aide de paires de *

**answer**

On peut également écrire des exemples de code dans notre documentation. On encadre la partie code avec "~~~" :

/**
Function that will return the text to show to the user according to his answer

Code example

~~~

if let ans = Int(resultat) {
    alert("Resultat", message: textForAnswer(ans))
}

~~~

Vous savez tout sur la documentation, ou presque ! ;)

Exemple de certificat de réussite
Exemple de certificat de réussite