Que mettre dans un docstring de module python? [fermé]

168

Ok, donc j'ai lu 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 que devrait contenir un module docstring. J'ai pensé, au minimum, qu'il devrait documenter les fonctions et les classes que le module exporte, mais j'ai également vu quelques modules qui répertorient les noms des auteurs, les informations de copyright, etc. être structuré?

python documentation module

Réponses:

183

Pensez à quelqu'un qui fait help(yourmodule)à l'invite de l'interprète interactif - que veut-il savoir? (D'autres méthodes d'extraction et d'affichage des informations sont à peu près équivalentes helpen termes de quantité d'informations). Donc, si vous avez x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

puis:

>>> import x; help(x)

spectacles:

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 une ici) sont déjà incluses à partir des docstrings de ces composants; la propre docstring du module devrait les décrire très sommairement (voire pas du tout) et se concentrer plutôt sur un résumé concis de ce que le module dans son ensemble peut faire pour vous, idéalement avec quelques exemples doctestinés (tout comme les fonctions et les classes devraient idéalement avoir des exemples doctestés dans leurs docstrings).

Je ne vois pas comment les métadonnées telles que le nom de l'auteur et les droits d'auteur / licence aident l'utilisateur du module - elles peuvent plutôt aller dans les commentaires, car cela pourrait aider quelqu'un à envisager de réutiliser ou de modifier le module.

— Alex Martelli
source

Alors, est-il habituel d'inclure l'auteur, le droit d'auteur, etc. dans les commentaires en haut d'un module?

@ 007brendan, c'est une pratique assez courante, oui.

— Alex Martelli

@IfLoop Je doute qu'il y ait plus d'utilisateurs qui utilisent la help()méthode dans l'interpréteur que d'utilisateurs qui lisent simplement le code.

— confused00

Gardez à l'esprit que la chose la plus importante à documenter est pourquoi . Documenter ce que fait quelque chose est le travail d'un code bien écrit. Documenter pourquoi est le travail de la documentation.

— Erik Aronesty

Pour citer les spécifications :

La docstring d'un script (un programme autonome) devrait être utilisable comme son message "usage", imprimé lorsque le script est appelé avec des arguments incorrects ou manquants (ou peut-être avec une option "-h", pour "help"). Une telle docstring devrait documenter la fonction du script et la syntaxe de la ligne de commande, les variables d'environnement et les fichiers. Les messages d'utilisation peuvent être assez élaborés (plusieurs écrans pleins) et devraient être suffisants pour qu'un nouvel utilisateur utilise correctement la commande, ainsi qu'une référence rapide complète à toutes les options et arguments pour l'utilisateur sophistiqué.

La docstring d'un module doit généralement lister les classes, exceptions et fonctions (et tout autre objet) qui sont exportées par le module, avec un résumé en une ligne de chacune. (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 d'un paquet (c'est-à-dire la docstring du __init__.pymodule du paquet ) doit également lister les modules et sous-paquets exportés par le paquet.

La docstring d'une classe doit 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 possède une interface supplémentaire pour les sous-classes, cette interface doit être répertoriée séparément (dans la docstring). Le constructeur de classe doit être documenté dans la docstring pour sa __init__méthode. Les méthodes individuelles doivent être documentées par leur propre docstring.

La docstring d'une fonction ou d'une méthode est une phrase se terminant par un point. Il prescrit l'effet de la fonction ou de la méthode comme une commande ("Faites ceci", "Renvoyez cela"), pas comme une description; par exemple, n'écrivez pas "Renvoie le chemin d'accès ...". Une docstring multiligne pour une fonction ou une méthode doit résumer son comportement et documenter ses arguments, valeur (s) de retour, effets secondaires, exceptions levées et restrictions sur le moment où elle peut être appelée (le cas échéant). Les arguments facultatifs doivent être indiqués. Il convient de documenter si les arguments de mot-clé font partie de l'interface.

— Remi
source