Vous pouvez documenter une fonction Python en lui donnant une chaîne de documentation (docstring).
Exemple 2.2. Définition d'une docstring 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 docstring.
 |
|
| 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 docstring de la fonction, qui décrit ce que fait la fonction. Une docstring, 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 docstring à 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 docstring est disponible à l'exécution en tant qu'attribut de fonction.
|
|
| Beaucoup d'IDE Python utilisent les docstring pour fournir une documentation contextuelle, ainsi lorsque vous tapez le nom d'une fonction, sa docstring apparaît dans une bulle d'aide. Cela peut être incroyablement utile, mais cette utilité est liée à la qualité de votre docstring. | |
Pour en savoir plus sur la documentation des fonctions
- La PEP 257 définit les conventions pour les docstring.
- Le Python Style Guide explique la manière d'écrire de bonnes docstring.
- Le Python Tutorial traite des conventions d'espacement dans les docstring.