Python/Funkcijų dokumentavimas

Galite dokumentuoti Python funkcijas aprašydami taip vadinamą „doc string“.

Pavyzdys 2.2. Funkcijos buildConnectionString dokumentavimas

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.

    Returns string."""

Trys kabutės reiškia simbolių eilutę, sudarytą iš kelių eilučių. Viskas turinys, esantis tarp trigubų kabučių yra vientisa simbolių eilutė, įskaitant ir naujas eilutes ir kitus kabučių simbolius. Tokias eilutes galite naudoti bet kur, tačiau dažniausiai jas matysite naudojamas funkcijų dokumentavimui (angl. „doc string“).

Trigubos kabutės, taip pat yra naudojamos kaip patogus būdas aprašyti simbolių eilutėms, kuriose yra ir viengubų ir dvigubų kabučių simbolių, Perl kalboje panaši išraiška atrodo taip: `qq/../`.

Viskas, kas parašyta tarp trigubų kabučių yra funkcijos dokumentacija (angl. doc string), kur aprašoma funkcijos paskirtis. Dokumentacijos eilutė doc string, jei ji yra, tai būtinai turi būti pirmas dalykas, aprašytas funkcijos viduje (pirmas dalykas, einantis po dvitaškio). Realiai funkcijos dokumentavimo eilutė nėra būtina, tačiau ją aprašyti rekomenduotina. Tikriausiai esate tai girdėję kiekvienoje programavimo pamokoje, kad programos kodą būtina dokumentuoti. Tačiau Python prideda papildomą paskatinimą, todėl, kad šios dokumentavimo eilutės yra pasiekiamos programos vykdymo metu, kaip funkcijos atributas.

Daugelis Python programavimo priemonių (IDE), naudoja dokumentavimo eilutes, kad pateiktų kaip kontekstinę pagalbą, kodo rašymo metu. Rašant funkcijos pavadinimą, gali būti rodoma jūsų aprašyta, funkcijos dokumentavimo eilutė. Tai gali būti labai naudinga, tačiau tai priklauso ir nuo to, kaip gerai dokumentuosite savo kodą...

Daugiau informacijos apie funkcijų dokumentavimą

• PEP 257 apibrėžtas susitarimas, kaip geriau dokumentuoti funkcijas.
• Python Stiliaus Gidas patarimai, kaip rašyti geras dokumentavimo eilutes.
• Python Vadovas diskusija apie dokumentavimo eilučių išlygiavimą.