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
- La PEP 257 définit les conventions pour les doc string.
- Le Python Style Guide explique la manière d'écrire de bonnes doc string.
- Le Python Tutorial traite des conventions d'espacement dans les doc string.