CKTIS / Python
docstring — dokumentačný reťazec
Docstring je bežný reťazcový literál (nie f-string ani t-string), ktorý tvorí prvý príkaz modulu, triedy alebo funkcie. Dokumentuje účel objektu a je dostupný cez __doc__; nie je to komentár začínajúci znakom #.
Verzia: Python 3.14; repository image, production runtime not attested
Syntax
def function_name():
"""Describe the function's purpose."""
passdocstring je bežný reťazcový literál (nie f-string ani t-string), ktorý tvorí prvý príkaz modulu, triedy alebo funkcie vrátane metódy. Python ho sprístupňuje ako atribút objektu __doc__. Nástroje môžu tento obsah použiť na zobrazenie dokumentácie.
Formátovaný reťazcový literál (f-string) ani šablónový reťazcový literál (t-string) nevytvorí docstring, ani keď literál neobsahuje žiadne substitučné polia a je prvým príkazom. Ak je prvým príkazom funkcie f"""Description.""", jej atribút __doc__ má hodnotu None.
Komentár začínajúci znakom # docstring nevytvára. Ani samostatný reťazcový literál umiestnený po inom príkaze sa nestane hlavným docstringom objektu. Trojité úvodzovky """...""" sú praktické, najmä pre viacero riadkov, ale samy osebe nestačia: záleží na druhu literálu aj na jeho umiestnení.
Podľa konvencie by mal prvý riadok stručne opísať účel objektu, začínať veľkým písmenom a končiť bodkou. Ďalší opis oddeľte prázdnym riadkom; podľa potreby vysvetlite argumenty, výsledky a vedľajšie účinky. Ide o odporúčania týkajúce sa obsahu, nie o požiadavky syntaxe.
V príklade sprístupňuje square.__doc__ opis, zatiaľ čo square(5) vypočíta výsledok nezávisle od dokumentácie. Voľba -OO odstraňuje docstringy, preto by kód aplikácie nemal závisieť od ich prítomnosti.
Príklady
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Výsledok
Return the square of number. 25
Zobrazený kód a uvedený výsledok boli overené v izolovanom prostredí metódou zaznamenanou v dôkaze o overení tejto presnej verzie.