Baza znanjaCentar za ispite
HRHrvatski
Odaberi jezik13

CKTIS / Python

docstring — dokumentacijski niz

Docstring je običan nizovni literal (nije ni f-niz ni t-niz) koji se koristi kao prva naredba modula, klase ili funkcije. Dokumentira svrhu objekta i dostupan je putem __doc__; nije komentar koji počinje znakom #.

Verzija: Python 3.14; repository image, production runtime not attested

Sintaksa

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

docstring je običan nizovni literal (nije ni f-niz ni t-niz) koji je postavljen kao prva naredba modula, klase ili funkcije, uključujući metodu. Python ga izlaže kao atribut objekta __doc__. Alati mogu upotrijebiti taj sadržaj za prikaz dokumentacije.

Ni formatirani nizovni literal (f-niz) ni predložak niza (t-niz) ne stvara docstring, čak ni ako literal ne sadrži polja za zamjenu i nalazi se na mjestu prve naredbe. Ako je prva naredba funkcije f"""Description.""", njezin atribut __doc__ ima vrijednost None.

Komentar koji počinje znakom # ne stvara docstring. Ni samostalni nizovni literal postavljen nakon druge naredbe ne postaje glavni docstring objekta. Trostruki navodnici """...""" praktični su, osobito za više redaka, ali sami po sebi nisu dovoljni: važni su i vrsta literala i njegov položaj.

Prema konvenciji, prvi redak trebao bi ukratko opisati svrhu objekta, početi velikim slovom i završiti točkom. Dodatni opis odvojite praznim retkom; po potrebi objasnite argumente, rezultate i nuspojave. To su smjernice za sadržaj, a ne sintaktički zahtjevi.

U primjeru square.__doc__ omogućuje pristup opisu, dok square(5) izračunava rezultat neovisno o dokumentaciji. Opcija -OO uklanja docstringove, pa se aplikacijski kod ne bi trebao oslanjati na njihovu prisutnost.

Primjeri

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

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

Rezultat

Return the square of number.
25

Prikazani kôd i navedeni rezultat provjereni su u izoliranom okruženju metodom zabilježenom u dokazu provjere za ovu točnu verziju.

Izvori