Docstrings Python - Commenter c`est aussi documenter !

Docstrings Python
Commenter c’est aussi documenter !
Adel Daouzli
LOL (LyonOpenLab) - Viveris Technologies
Mél : [email protected]
Web : http://www.daouzli.com/blog/pyconfr-fr.html
25/10/2014
Adel Daouzli Docstrings - Python 1 / 30

Plan
1Introduction
2Recommandations
3Formats de docstrings
4Pyment
5Outils génération de doc
6Questions ?
Adel Daouzli Docstrings - Python 2 / 30

Introduction
Commentaires
Commenter...
//C ++
/* C, Java , Ja vas cri pt ,... */
#Python /sh
...
Bdescription / compréhension / collaboration
Bannotations / tags (__AUTHOR__, __DATE__, FIXME, TODO)
Bautogénération de documentation
Adel Daouzli Docstrings - Python 3 / 30

Introduction
Autogénération Documentation (Doxygen/Javadoc)
- pionniers (fin du XXe siècle)
- commentaires annotés / taggés -> documentation
BDoxygen:
parse tags spécifiques (\brief, \param, \retval,...) C/C++ (d’autres dont
Python) Exemple:
/** \ brief Br ève description .
*
* Desc ript ion plus détaill ée.
* \param p1 un paramè tre
* \return le resultat de la fonction
* \retval -1 é chec
*/
int fonction (int p1 );
BJavadoc tool: parse tags (@param, @return, @rtype,...) Exemple:
/** Description de la fonction .
*
* @param p1 : un paramè tre
* @type p1: int
* @return: le resultat de la fonction
* @rtype: int
*/
int fonction (int p1 );
Adel Daouzli Docstrings - Python 4 / 30

Introduction
Python Docstrings (syntaxe, help, __doc__, doctest)
B« documentation string »
B2 délimiteurs possible (’ ’ ’, " " ")
Bchaine de caractère multiligne
Bdescription : début fonction / 1ers args de classe (__init__)
Bdoctest -> petits tests
"""
>>> a = 2
>>> b = 5
>>> a + b
7
"""
Adel Daouzli Docstrings - Python 5 / 30