Python/Funkcijų dokumentavimas: Skirtumas tarp puslapio versijų

Ištrintas turinys Pridėtas turinys
Sirex (aptarimas | indėlis)
Naujas puslapis: Galite dokumentuoti Python funkcijas aprašydami taip vadinamą ''doc string''. {{Stub}} Kategorija:Python
 
Sirex (aptarimas | indėlis)
Nėra keitimo santraukos
1 eilutė:
Galite dokumentuoti Python funkcijas aprašydami taip vadinamą ''doc string''.
 
'''Pavyzdys 2.2. Funkcijos buildConnectionString dokumentavimas'''
 
<source lang="python">
def buildConnectionString(params):
"""Build a connection string from a dictionary of parameters.
 
Returns string."""
</source>
 
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ą'''
* [http://www.python.org/peps/pep-0257.html PEP 257] apibrėžtas susitarimas, kaip geriau dokumentuoti funkcijas.
* [http://www.python.org/doc/essays/styleguide.html Python Stiliaus Gidas] patarimai, kaip rašyti geras dokumentavimo eilutes.
* [http://www.python.org/doc/current/tut/tut.html Python Vadovas] diskusija apie dokumentavimo eilučių [http://www.python.org/doc/current/tut/node6.html#SECTION006750000000000000000 išlygiavimą].
 
{{Stub}}