2.3. Documentation des fonctions
Vous pouvez documenter une fonction
Python en lui donnant une chaîne de
documentation (doc string).
Exemple 2.2. Définition d'une doc string pour la fonction buildConnectionString
def buildConnectionString(params):
"""Build a connection string from a dictionary of parameters.
Returns string."""Les tripes guillemets indiquent une chaîne multi-lignes. Tout ce qu'il y a entre l'ouverture et la fermeture des guillemets
fait partie de la chaîne, y compris les retours chariot et les autres guillemets. On peut les utiliser partout, mais vous
les verrez le plus souvent utilisées pour définir une doc string.
 |
| Les triples guillemets sont aussi un moyen simple de définir une
chaîne contenant à la fois des guillemets simples et doubles, comme
qq/.../ en Perl.
|
Tout ce qui se trouve entre les triples guillemets fait partie de la
doc string de la fonction, qui décrit ce que fait la
fonction. Une doc string, si elle existe, doit être
la première chose déclarée dans une fonction (la première chose après
les deux points). Techniquement parlant, vous n'êtes pas obligés de
donner une doc string à votre fonction, mais vous
devriez toujours le faire. Je sais que vous avez entendu cela à tous les
cours de programmation auxquels vous avez assisté mais
Python vous donne une motivation
supplémentaire : la doc string est disponible à
l'exécution en tant qu'attribut de fonction.
|
| Beaucoup d'IDE Python utilisent les doc string pour fournir une documentation contextuelle, ainsi lorsque vous tapez le nom d'une fonction, sa doc string apparaît dans une bulle d'aide. Cela peut être incroyablement utile, mais cette utilité est liée à la qualité de votre doc string.
|
Pour en savoir plus sur la documentation des fonctions
