La documentation des fonctions

Les Docstrings en Python

La documentation des fonctions en Python se fait à l’aide de docstrings. Un docstring est un bloc de commentaires qui se trouve au début du corp de la fonction. Elle sert à définir une fonction, ses paramètres et sa valeur de retour.

Pour générer automatiquement le docstring, entrez « """ », ensuite appuyez sur la touche « Entrée ». Une chaine de caractères formattée va apparaitre. Elle contient des mots clés « :param » pour chaque paramètre de la fonction que vous devez définir (s’ils existent) et un mot « :return » si la fonction a une valeur de retour que vous devez définir.

Docstring généré AVANT la description de la fonction, des paramètres et de la valeur de retour

Docstring généré APRÈS la description de la fonction, des paramètres et de la valeur de retour

Exemple

def trouver_element(liste, element):
    """
    Cette fonction recherche un élément dans une liste et renvoie True si l'élément est trouvé, False sinon.

    :param liste: La liste dans laquelle rechercher
    :param element: L'élément à rechercher dans la liste.
    :return: True si l'élément est trouvé, False sinon.
    """

    if element in liste:
        return True
    else:
        return False

if __name__ == "__main__" :
    ma_liste = [1, 2, 3, 4, 5]
    
    # Appel de la fonction
    element_est_trouve = trouver_element(ma_liste, 3)
    print(element_est_trouve)

Vous pouvez ajouter un exemple dans la documentation de votre fonction :

def trouver_element(liste, element):
    """
    Cette fonction recherche un élément dans une liste et renvoie True si l'élément est trouvé, False sinon.

    :param liste: La liste dans laquelle rechercher
    :param element: L'élément à rechercher dans la liste.
    :return: True si l'élément est trouvé, False sinon.
    
    Example:
        ma_liste = [1, 2, 3, 4, 5]

        trouver_element(ma_liste, 3) --> True

        trouver_element(ma_liste, 6) --> False
    """
    
    if element in liste:
        return True
    else:
        return False

if __name__ == "__main__" :

    ma_liste = [1, 2, 3, 4, 5]
    
    # Appel de la fonction
    element_est_trouve = trouver_element(ma_liste, 3)
    print(element_est_trouve)

Comment se servir des docstrings ?

• En lisant le docstring dans le code source

• En positionnant le curseur de votre souris au dessus de l'appel à la fonction.

• [Hors cours] En générant automatiquement un fichier de documentation tel que

  • Un README en utilisant la librairie pdoc.

  • Des documents HTML en utilisant des outils de documentation automatique tels que Sphinx, Doxygen ou pydoc intégré à Python.