# 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**.

<figure><img src="https://700524925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn5YnWU89G98lz0ROIcGu%2Fuploads%2FqWrAaEhScOPKHbW6rWr7%2Fimage.png?alt=media&#x26;token=15254fec-50f8-4e77-a118-cb05d008b59a" alt=""><figcaption><p>Docstring généré AVANT la description de la fonction, des paramètres et de la valeur de retour </p></figcaption></figure>

<figure><img src="https://700524925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn5YnWU89G98lz0ROIcGu%2Fuploads%2F0cclpWTcQDk970rMJoLE%2Fimage.png?alt=media&#x26;token=75d7a472-f5f5-41e1-9316-a1be6a9b0820" alt=""><figcaption><p>Docstring généré APRÈS la description de la fonction, des paramètres et de la valeur de retour </p></figcaption></figure>

### Exemple

<pre class="language-python"><code class="lang-python">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.
    """

<strong>    if element in liste:
</strong>        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)
</code></pre>

{% hint style="success" %}

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

```python
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)

```

{% endhint %}

## 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.

<figure><img src="https://700524925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn5YnWU89G98lz0ROIcGu%2Fuploads%2FY0y4o7adcps56NDpfhRg%2Fimage.png?alt=media&#x26;token=dd84f45b-39fb-415c-a179-415e6e28a638" alt=""><figcaption></figcaption></figure>

* <mark style="background-color:red;">\[Hors cours]</mark> 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.
