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