Znalostná bázaCentrum skúšok
SKSlovenčina
Vybrať jazyk13

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

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

Zdroje