CKTIS / Python
docstring — documentatietekst
Een docstring is een gewone tekenreeksliteral (geen f-string of t-string) die als eerste instructie van een module, klasse of functie staat. De tekst documenteert het doel van het object en is beschikbaar via __doc__; het is geen commentaar dat begint met #.
Versie: Python 3.14; repository image, production runtime not attested
Syntax
def function_name():
"""Describe the function's purpose."""
passEen docstring is een gewone tekenreeksliteral (geen f-string of t-string) die als eerste instructie van een module, klasse of functie staat. Dit geldt ook voor methoden. Python stelt de tekst beschikbaar als het attribuut __doc__ van het object. Hulpmiddelen kunnen deze inhoud gebruiken om documentatie weer te geven.
Een geformatteerde tekenreeksliteral (f-string) en een sjabloonliteral (t-string) leveren geen docstring op, ook niet als de literal geen vervangingsvelden bevat en als eerste instructie staat. Als de eerste instructie van een functie f"""Description.""" is, heeft het attribuut __doc__ van die functie de waarde None.
Commentaar dat begint met # levert geen docstring op. Een zelfstandige tekenreeksliteral na een andere instructie wordt evenmin de hoofd-docstring van het object. Drievoudige aanhalingstekens """...""" zijn handig, vooral voor meerdere regels, maar zijn op zichzelf niet voldoende: zowel het soort literal als de positie ervan telt.
Volgens de conventie beschrijft de eerste regel kort het doel van het object, begint deze met een hoofdletter en eindigt hij met een punt. Scheid verdere uitleg met een lege regel; licht zo nodig argumenten, resultaten en neveneffecten toe. Dit zijn richtlijnen voor de inhoud, geen syntaxisvereisten.
In het voorbeeld geeft square.__doc__ toegang tot de beschrijving, terwijl square(5) het resultaat berekent, onafhankelijk van de documentatie. De optie -OO verwijdert docstrings. Applicatiecode moet daarom niet afhankelijk zijn van hun aanwezigheid.
Voorbeelden
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Resultaat
Return the square of number. 25
De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.