Oorspronkelijke reden(en) zijn niet opgelost
Antwoord 1, autoriteit 100%
Denk aan iemand die help(yourmodule)doet op de prompt van de interactieve tolk — wat willen ze willenweten? (Andere methoden om de informatie te extraheren en weer te geven zijn qua hoeveelheid informatie ongeveer gelijk aan help). Dus als je in x.py:
"""This module does blah blah."""
class Blah(object):
"""This class does blah blah."""
dan:
>>> import x; help(x)
shows:
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)
Zoals je ziet, is de gedetailleerde informatie over de klassen (en ook functies, hoewel ik er hier geen laat zien) al opgenomen in de docstrings van die componenten; de eigen docstring van de module zou ze heel summier moeten beschrijven (of helemaal niet) en zich liever concentreren op een beknopte samenvatting van wat de module als geheel voor je kan doen, idealiter met enkele doc-geteste voorbeelden (net zoals functies en klassen idealiter doc-geteste voorbeelden zouden moeten hebben in hun docstrings).
Ik zie niet in hoe metadata zoals de naam van de auteur en copyright / licentie de gebruiker van de module helpt — het kan liever in opmerkingen worden geplaatst, omdat het iemand kan helpen bij het overwegen om de module al dan niet opnieuw te gebruiken of aan te passen.
Antwoord 2, autoriteit 25%
Om de specificatieste citeren:
De docstring van een script
(een op zichzelf staand programma) zou bruikbaar moeten zijn als zijn “gebruiks”-bericht, afgedrukt wanneer het script wordt aangeroepen met onjuiste of ontbrekende argumenten (of misschien met een “-h” optie, voor “help”). Een dergelijke docstring zou de functie van het script en de syntaxis van de opdrachtregel, omgevingsvariabelen en bestanden moeten documenteren. Gebruiksberichten kunnen behoorlijk uitgebreid zijn (meerdere schermen vol) en zouden voldoende moeten zijn voor een nieuwe gebruiker om de opdracht correct te gebruiken, evenals een volledige snelle verwijzing naar alle opties en argumenten voor de ervaren gebruiker.De docstring voor een module
moet over het algemeen de klassen, uitzonderingen en functies (en alle andere objecten) vermelden die door de module worden geëxporteerd, met een samenvatting van elk in één regel. (Deze samenvattingen geven over het algemeen minder details dan de samenvattingsregel in de docstring van het object.) De docstring voor een pakket (dwz de docstring van de module__init__.pyvan het pakket) zou ook de geëxporteerde modules en subpakketten moeten vermelden per pakket.De docstring voor een klasse
moet zijn gedrag samenvatten en de openbare methoden en instantievariabelen vermelden. Als het de bedoeling is dat de klasse wordt gesubklasseerd en een extra interface voor subklassen heeft, moet deze interface afzonderlijk worden vermeld (in de docstring). De klassenconstructor moet worden gedocumenteerd in de docstring voor zijn__init__-methode. Individuele methoden moeten worden gedocumenteerd door hun eigen docstring.
De docstring van een functieof methode
is een zin die eindigt op een punt. Het schrijft het effect van de functie of methode voor als een commando (“Doe dit”, “Return that”), niet als een beschrijving; bijv. schrijf niet “Retourneert de padnaam …”. Een multiline-docstring voor een functie of methode moet zijn gedrag samenvatten en zijn argumenten documenteren, waarde(n) retourneren, bijwerkingen, opgeworpen uitzonderingen en beperkingen op wanneer het kan worden aangeroepen (allemaal indien van toepassing). Optionele argumenten moeten worden aangegeven. Er moet worden gedocumenteerd of trefwoordargumenten deel uitmaken van de interface.