EOLE

h1. DocumentationCodeBonnesPratiques

h2. Généralité

* La documentation technique doit être en anglais.

* Elle est placé dans les docstrings du code.

h2. Description du module

La docstring du module est placée en haut du fichier.

La docstring doit contenir :

* description rapide en une phrase du module ;

* description avancée qui explique le rôle du module ;

* des exemples simples d'utilisation.

Les exemples peuvent être un prompt :

<pre>

    >>> is_locked()

    True

</pre>

ou une portion de code :

<pre>

    ::

        from toto.titi import is_locked

        toto()

        is_locked()

</pre>

h2. Docstring des méthodes

Seules les méthodes publiques (qui ne commencent pas par "_") seront mises dans la documentation (mais les méthodes privées sont aussi à documentée).

La docstring doit contenir :

* description rapide en une phrase de la méthode ;

* si nécessaire une description avancée qui explique le rôle du module ;

* si nécessaire des exemples simples d'utilisation.

* les paramètres de la façon suivante (xxx étant le nom du paramètre et yyyyyy la description) :

<pre>

    :param xxx: yyyyyy

</pre>

Si nécessaire les valeurs de retour (yyyyyy étant la description) :

<pre>

    :return: yyyyyy

</pre>

h2. Docstring des classes

A faire