Python docstring

Dokumentácia je nevyhnutná pre každé programovanie, aby ľahko pochopila kód. Používa sa na vysvetlenie účelu použitia ktoréhokoľvek príkazu alebo funkcie alebo triedy alebo modulu v programe. Pomáha hlavnému kódovačovi po dlhom čase zapamätať si funkciu ľubovoľného kódu. Pomáha tiež ďalším kódovačom, ktorí chcú pracovať na rovnakom projekte. Kodér používa jediný riadok komentára na krátke vysvetlenie konkrétnej časti funkcie kódu. Reťazec dokumentu alebo docstring v jazyku Python sa používa na podrobné vysvetlenie funkcie konkrétneho segmentu kódu. Riadok s dokumentom by sa mal začínať veľkým písmenom a končiť bodkou. Prvý riadok dokumentačného reťazca obsahuje všeobecný krátky popis dokumentácie. Druhý riadok dokumentového reťazca by mal byť pre veľký viacriadkový dokumentový reťazec prázdny. Trojité jednoduché úvodzovky („“) alebo trojité dvojité úvodzovky („“) sa používajú na definovanie dokumentačného reťazca v Pythone. Obsah dokumentu je prístupný pomocou __doc__ atribút objektu a pomocou Pomoc() metóda. V tomto návode sa ukázal spôsob deklarovania a prístupu k dokumentovému reťazcu v Pythone.

Príklad 1: Prístup k dokumentovému reťazcu funkcie pomocou __doc__ atribút

Spôsob deklarovania a prístupu k dokumentu vlastnej funkcie je uvedený v nasledujúcom skripte. Nasledujúci skript počíta znak xⁿ kde x a n budú prevzaté od používateľa. Moc () funkcia definovala v skripte vykonanie úlohy. Tu bol pre túto funkciu definovaný dokumentačný reťazec. __doc__ sa v skripte použil atribút na tlač dokumentu s výstupom.

def power (x, n):
"Vypočítajte x na mocninu n
Prečítajte si hodnoty x a n z argumentov funkcie
a Vypočítaj a vráť hodnotu x na mocninu n.„
návrat x ** n
# Vezmite hodnotu x
x = int (vstup ('Zadajte hodnotu x:'))
# Vezmite hodnotu n
n = int (vstup ('Zadajte hodnotu n:'))
# Vytlačte návratnú hodnotu funkcie
print ("% d k výkonu% d =% d"% (x, n, výkon (x, n)))
# Vytlačte hodnotu dokumentu
print ("Obsah dokumentačného reťazca: \ n" + sila.__doc__)

Výkon:

Po vykonaní vyššie uvedeného skriptu sa zobrazí nasledujúci výstup.

Príklad-2: Prístup k dokumentovému reťazcu triedy a metódy pomocou Pomoc() metóda

Spôsob deklarovania a prístupu k dokumentovému reťazcu dokumentu a metódam tejto triedy je uvedený v nasledujúcom skripte. Hlavnou funkciou skriptu je triedenie číselného zoznamu a obrátenie údajov zoznamu. V triede bol deklarovaný číselný zoznam 8 prvkov a dokumentačný reťazec bol definovaný na začiatku triedy pomocou trojitých jednoduchých úvodzoviek. V triede bola definovaná metóda sort_list () na tlačenie zoradených údajov zo zoznamu a dokument to definoval pre túto metódu. reverse_list () je definovaná metóda tlače obrátených údajov zoznamu a pre túto metódu bol tiež definovaný dokumentačný reťazec. Pomoc() metóda volala trikrát na konci skriptu, aby vytlačila dokumentačný súbor list_operations trieda, zoradiť_zoznam () metóda a reverse_list () metóda.

zoznam_operácií triedy:

zoznam_operácií triedy:
„
Triedenie a obrátenie údajov zoznamu
Trieda obsahuje dve metódy,
metóda sort_list () zoznam zoradí a vytlačí,
metóda sort_reverse () obráti zoznam a vytlačí ho.
„
# Definujte zoznam číselných údajov
listdata = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (self):
„
Po zoradení vytlačte hodnoty zoznamu
Funkcia prevezme z argumentu objekt zoznamu číselných údajov,
zoradiť hodnoty zoznamu pomocou metódy sort ()
a vytlačiť hodnoty zoradeného zoznamu.
„
# Zoradiť zoznam
ja.listdata.sort ()
# Vytlačte zoradený zoznam pomocou slučky
print ("Hodnoty zoradeného zoznamu: \ n")
pre hodnotu v sebe.listdata:
print (value, "", end = ")
def reverse_list (self):
„
Po obrátení vytlačte hodnoty zoznamu
Funkcia prevezme z argumentu objekt zoznamu číselných údajov,
obrátiť hodnoty zoznamu pomocou metódy reverse ()
a vytlačiť hodnoty obráteného zoznamu.
„
# Obrátiť zoznam
ja.listdata.reverz ()
# Vytlačiť obrátený zoznam pomocou slučky
print ("Hodnoty zoradeného zoznamu: \ n")
pre hodnotu v sebe.listdata:
print (value, "", end = ")
# Vytlačte hodnotu docstring triedy
pomoc (zoznam_operácií)
# Vytvorte objekt triedy
obj = list_operations ()
# Vytlačte hodnotu dokumentačného reťazca konkrétnej metódy
pomoc (obj.zoradiť_zoznam)
# Zavolajte metódu na vytlačenie zoradeného zoznamu
obj.zoradiť_zoznam ()

Výkon:

Po vykonaní skriptu sa zobrazí nasledujúci výstup. Celý dokumentačný skript bol vytlačený ako prvý Pomoc() funkcia. Dokument z zoradiť_zoznam () metóda bola vytlačená pre druhú Pomoc() funkcia.

Príklad 3: Prístup k dokumentačnému reťazcu vstavaného modulu Python

V predchádzajúcich príkladoch sa dokumentačný reťazec používal v používateľom definovanej triede a funkcii. Každý vstavaný modul a trieda Python má svoj dokumentačný reťazec, ktorý vysvetľuje účel použitia konkrétneho modulu alebo funkcie. Kodér modulu alebo funkcie definuje dokumentačný reťazec, aby bol kód pre používateľov zrozumiteľný. Nasledujúci skript vytlačí preddefinovaný dokumentový reťazec modulu datetime pomocou Pomoc() funkcia.

# Importovať modul datetime
importovať čas a čas
# Zobraziť dokumentačný reťazec datetime
pomoc (datetime)

Výkon:

Po vykonaní skriptu sa zobrazí nasledujúci výstup. Dokumentačný modul modulu datetime zobrazuje jeho podrobnú dokumentáciu, ktorá pomáha ostatným správne poznať funkcie tried a metód definovaných v tomto module.

Záver:

Správna dokumentácia je nevyhnutná, ak je ktorýkoľvek modul alebo funkcia implementovaná na konkrétny účel, aby pomohol druhému kodérovi použiť modul v ich kóde na vykonanie konkrétnej úlohy. Ak nie je dokumentácia pre modul alebo funkciu správne definovaná, ostatní používatelia sa pri jej používaní stretnú s problémami. Každý programátor teda musí použiť dokumentačný dokument dokumentu, aby poskytol ďalšie informácie, aby ostatní porozumeli kódu.