Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

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."""
    pass

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, 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.

Zdroje