Baza znanjaIzpitno središče
SLSlovenščina
Izberi jezik13

CKTIS / Python

docstring — dokumentacijski niz

Docstring je običajen nizovni literal (ne f-niz ali t-niz), uporabljen kot prvi stavek modula, razreda ali funkcije. Dokumentira namen objekta in je dostopen prek __doc__; ni komentar, ki se začne z #.

Različica: Python 3.14; repository image, production runtime not attested

Sintaksa

def function_name():
    """Describe the function's purpose."""
    pass

docstring je običajen nizovni literal (ne f-niz ali t-niz), uporabljen kot prvi stavek modula, razreda ali funkcije, tudi metode. Python ga izpostavi kot atribut objekta __doc__. Orodja lahko to vsebino uporabijo za prikaz dokumentacije.

Niti oblikovani nizovni literal (f-niz) niti predložni nizovni literal (t-niz) ne ustvari docstringa, tudi če literal ne vsebuje nadomestnih polj in je prvi stavek. Če je prvi stavek funkcije f"""Description.""", ima njen atribut __doc__ vrednost None.

Komentar, ki se začne z #, ne ustvari docstringa. Tudi samostojen nizovni literal, postavljen za drugim stavkom, ne postane glavni docstring objekta. Trojni narekovaji """...""" so priročni, zlasti za več vrstic, vendar sami po sebi ne zadoščajo: pomembni sta tako vrsta literala kot njegova umestitev.

Po konvenciji naj prva vrstica na kratko opiše namen objekta, se začne z veliko začetnico in konča s piko. Dodatni opis ločite s prazno vrstico; po potrebi pojasnite argumente, rezultate in stranske učinke. To so priporočila glede vsebine, ne sintaktične zahteve.

V primeru square.__doc__ omogoča dostop do opisa, medtem ko square(5) izračuna rezultat neodvisno od dokumentacije. Možnost -OO odstrani docstringe, zato se koda aplikacije ne bi smela zanašati na njihovo prisotnost.

Primeri

def square(number):
    """Return the square of number."""
    return number * number

print(square.__doc__)
print(square(5))

Rezultat

Return the square of number.
25

Prikazana koda in navedeni rezultat sta bila preverjena v izoliranem okolju z metodo, zapisano v dokazilu o preverjanju te natančne različice.

Viri