CKTIS / Python
docstring — dokumentační řetězec
Docstring je běžný řetězcový literál (nikoli f-string ani t-string), který stojí jako první příkaz modulu, třídy nebo funkce. Dokumentuje účel objektu a je dostupný přes __doc__; nejde o komentář začínající znakem #.
Verze: Python 3.14; repository image, production runtime not attested
Syntaxe
def function_name():
"""Describe the function's purpose."""
passdocstring je běžný řetězcový literál (nikoli f-string ani t-string), který stojí jako první příkaz modulu, třídy nebo funkce, včetně metody. Python jej zpřístupňuje jako atribut objektu __doc__. Nástroje mohou tento obsah využít k zobrazení dokumentace.
Formátovaný řetězcový literál (f-string) ani šablonový řetězcový literál (t-string) nevytvoří docstring, ani když literál neobsahuje žádná substituční pole a stojí jako první příkaz. Pokud je prvním příkazem funkce f"""Description.""", má její atribut __doc__ hodnotu None.
Komentář začínající znakem # docstring nevytváří. Ani samostatný řetězcový literál umístěný po jiném příkazu se nestane hlavním docstringem objektu. Trojité uvozovky """...""" jsou praktické, zejména pro více řádků, ale samy o sobě nestačí: záleží jak na druhu literálu, tak na jeho umístění.
Podle konvence by první řádek měl stručně popsat účel objektu, začínat velkým písmenem a končit tečkou. Další popis oddělte prázdným řádkem; podle potřeby vysvětlete argumenty, výsledky a vedlejší účinky. Jde o doporučení k obsahu, nikoli o požadavky syntaxe.
V příkladu zpřístupňuje square.__doc__ popis, zatímco square(5) vypočítá výsledek nezávisle na dokumentaci. Volba -OO docstringy odstraňuje, proto by kód aplikace neměl záviset na jejich přítomnosti.
Příklady
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Výsledek
Return the square of number. 25
Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.