DocumentationCodeBonnesPratiques » Historique » Version 7
« Précédent -
Version 7/34
(diff) -
Suivant » -
Version actuelle
Emmanuel GARETTE, 12/12/2012 16:50
DocumentationCodeBonnesPratiques¶
Généralité¶
- La documentation technique doit être en anglais.
- Elle est placée dans les docstrings du code.
Description du module¶
La docstring du module est placée en haut du fichier.
La docstring doit contenir :
- la licence du code
########################################################################### # EOLE # Copyright Pole de Competence EOLE (Ministere Education - Academie Dijon) # Licence CeCILL http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html # eole@ac-dijon.fr ###########################################################################
- 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 :
>>> is_locked() True
ou une portion de code :
:: from toto.titi import is_locked toto() is_locked()
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 à documenter).
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) :
:param xxx: yyyyyy
Si nécessaire les valeurs de retour (yyyyyy étant la description) :
:return: yyyyyy
plus d'info sur la syntaxe des docstrings: http://sphinx-doc.org/domains.html#info-field-lists
Docstring des classes¶
A faire