Que mettre dans un module Python docstring? [fermé]
Ok, donc j'ai lu à la fois PEP 8 et pep 257, et j'ai écrit beaucoup de docstrings pour les fonctions et les classes, mais je ne suis pas sûr de ce qui devrait aller dans un module docstring. J'ai pensé, au minimum, qu'il devrait documenter les fonctions et les classes que le module exporte, mais j'ai aussi vu quelques modules qui listent les noms d'auteur, les informations de copyright, etc. Quelqu'un at-il un exemple de la façon dont un bon docstring Python devrait être structuré?
2 réponses
Pensez à quelqu'un qui fait help(yourmodule) à l'invite de l'interprète interactif -- que veulent-ils savoir? (D'autres méthodes d'extraction et d'affichage des informations sont à peu près équivalentes à help en termes de quantité d'informations). Donc, si vous avez dans x.py:
"""This module does blah blah."""
class Blah(object):
"""This class does blah blah."""
Puis:
>>> import x; help(x)
Affiche:
Help on module x:
NAME
x - This module does blah blah.
FILE
/tmp/x.py
CLASSES
__builtin__.object
Blah
class Blah(__builtin__.object)
| This class does blah blah.
|
| Data and other attributes defined here:
|
| __dict__ = <dictproxy object>
| dictionary for instance variables (if defined)
|
| __weakref__ = <attribute '__weakref__' of 'Blah' objects>
| list of weak references to the object (if defined)
Comme vous le voyez, les informations détaillées sur les classes (et les fonctions aussi, bien que je n'en montre pas ici) sont déjà incluses à partir de ces composants' docstrings; la propre docstring du module devrait les décrire très sommairement (le cas échéant) et plutôt se concentrer sur un résumé concis de ce que le module dans son ensemble peut faire pour vous, idéalement avec quelques exemples doctested (tout comme les fonctions et les classes devraient idéalement avoir des exemples doctested dans theit docstrings).
Je ne vois pas comment les métadonnées telles que le nom de l'auteur et le droit d'auteur / licence aident l'utilisateur du module - il peut plutôt aller dans les commentaires, car cela pourrait aider quelqu'un à déterminer si ou ne pas réutiliser ou modifier le module.
Pour citer les spécifications :
La docstring d'un script (un programme autonome) devrait être utilisable comme son message "utilisation", imprimé lorsque le script est appelé avec des arguments incorrects ou manquants (ou peut-être avec une option" - h", Pour"help"). Un tel docstring doit documenter la fonction et la syntaxe de ligne de commande du script, les variables d'environnement et les fichiers. Les messages d'utilisation peuvent être assez élaborés (plusieurs écrans pleins) et devraient être suffisants pour un nouveau utilisateur d'utiliser la commande correctement, ainsi qu'une référence rapide complète à toutes les options et arguments pour l'utilisateur sophistiqué.
La docstring pour un module devrait généralement énumérer les classes, les exceptions et les fonctions (et tous les autres objets) qui sont exportés par le module, avec un résumé d'une ligne de chacun. (Ces résumés donnent généralement moins de détails que la ligne de résumé dans la docstring de l'objet.) La docstring pour un paquet (c'est-à-dire la docstring du paquet
__init__.pymodule) devrait également répertorier les modules et sous-paquets exportés par le paquet.La docstring pour une classe devrait résumer son comportement et répertorier les méthodes publiques et les variables d'instance. Si la classe est destinée à être sous-classée et dispose d'une interface supplémentaire pour les sous-classes, cette interface doit être listée séparément (dans docstring). Le constructeur de classe doit être documenté dans docstring pour sa méthode
__init__. Les méthodes individuelles doivent être documentées par leur propre docstring.
La docstring de function ou méthode est une phrase se terminant par une période. Il prescrit l'effet de la fonction ou de la méthode comme une commande ("Do this"," Return that"), pas comme une description; par exemple, don't write " renvoie le chemin ...". Un multiligne-docstring pour une fonction ou une méthode doit résumer son comportement et documenter ses arguments, ses valeurs de retour, ses effets secondaires, ses exceptions soulevées et ses restrictions sur le moment où il peut être appelé(le cas échéant). Les arguments facultatifs doivent être indiqués. Il devrait être documenté si les arguments de mot-clé font partie de l'interface.