Keďže už vieme, ako písať viacriadkové komentáre, môžeme použiť jednoduché jednoduché úvodzovky alebo trojité dvojité úvodzovky. Dokumentačný reťazec používame, keď chceme opísať naše funkcie, aby sme mohli získať dokumentáciu, keď ju potrebujeme. Niektoré IDE vám poskytnú dokumentáciu jednoduchým umiestnením kurzora myši nad názov a niektoré zvýraznia určité kľúčové slová. Faktom však je, že reťazce dokumentov v NumPy sú oveľa flexibilnejšie ako v iných jazykoch. Docstring je reťazcový literál, ktorý sa vyskytuje na začiatku definície funkcie. Pri používaní docstringov v prípadoch funkcií, tried atď. musíme poskytnúť konkrétne hodnoty.
Pri použití reťazcov docstring s funkciami musíme odovzdať argumenty. Pri ich použití s triedami odovzdávame atribúty a metódy. V prípade modulov musíme poskytnúť zoznam tried a funkcií. V prípade balíka odovzdávame zoznam modulov s funkčnosťou. Takže v podstate účelom docstringu je, ako už názov vysvetľuje, že pomáha s dokumentáciou nášho kódu. Robíme dokumentáciu tak, že ak niekto použije náš kód v budúcnosti, bude schopný pochopiť náš kód a logiku nášho kódu pomocou docstringu. Vstavané funkcie majú v sebe aj dokumentačné reťazce; môžeme použiť funkciu help(), aby sme sa pozreli na dokumentačný reťazec vstavaných funkcií.
Medzi komentármi a dokumentačnými reťazcami je niekoľko rozdielov. Tlmočníci ignorujú komentáre, ale tlmočníci ignorujú reťazce dokumentov. Pamäť je alokovaná pre dokumentačné reťazce. Komentár je popis kódu, ale na druhej strane nám reťazce dokumentov hovoria o účele kódu.
Syntax:
Syntax na písanie reťazcov dokumentov v NumPy je:
'''Správa dokovacieho reťazca'''
Alebo
'''Správa dokovacieho reťazca'''
Upozorňujeme, že docstring nie je funkcia ani metóda, takže nemá správnu syntax. Jediná vec, ktorú je potrebné poznamenať, je, že dokumentačný reťazec začíname tromi jednoduchými úvodzovkami alebo tromi dvojitými úvodzovkami. Napíšeme náš popis kódu a zakončíme ho opäť tromi jednoduchými úvodzovkami alebo tromi dvojitými úvodzovkami na konci. Pre dokumentačné reťazce nie je potrebné nič písať. Stačí vložiť tri jednoduché alebo dvojité úvodzovky pred a za popis reťazca.
Príklad 1:
Aby sme lepšie porozumeli dokumentačným reťazcom, uvedieme príklad. V tomto príklade po zahrnutí knižnice NumPy jednoducho deklarujeme premennú „a“ a ďalšiu premennú „b“. Potom vytvoríme náš dokumentačný reťazec, ktorý hovorí „Pridajme premenné „a“ a „b“. V našom prípade je to jednoduchý príklad, ale ak je náš kód zložitý, kóderovi to veľmi pomôže pochopiť kód. Potom spočítame premenné „a“ a „b“ a ich výstupný výsledok uložíme do inej premennej, ktorá je „c“. Nakoniec vypíšeme hodnotu premennej „c“. Teraz spustíme náš kód.
importovať numpy ako napr.a = 1
b = dva
'''Pridajme premenné aab'''
c = a+b
vytlačiť ( c )
Toto je náš výstup z daného kusu kódu. Vidíme, že systém neposkytol žiadnu chybu o nesprávnej syntaxi alebo niečom inom pre riadok 7 nášho kódu. Systém tiež nevytlačil náš dokumentačný reťazec. Namiesto toho vytlačil iba výstup našej premennej „c“, v ktorej sme nášmu systému povedali, aby vytlačil. Toto ukazuje, ako fungujú reťazce dokumentov. Nabudúce, keď sa nový kóder pokúsi pracovať na našom kóde, pochopí, čo robíme s pomocou nášho dokumentačného reťazca. Nebude však vytlačený ako výstup, takže používateľ kódu nebude rušený.
Príklad 2:
Teraz uvedieme komplexný príklad, aby sme pochopili fungovanie dokumentačného reťazca. Najprv zahrnieme knižnicu NumPy a potom napíšeme reťazec doc, v ktorom vysvetlíme ďalší riadok kódu, kde vysvetlíme inicializáciu poľa. Dokumentačné reťazce pridávame aj do druhej časti kódu. Teraz, ak zdieľame tento kód s akýmkoľvek novým vývojárom Pythonu bez pridania docstringov, bude pre neho nejako ťažké poznať fungovanie a účel tohto kódu. Najprv musí hľadať funkcie, ktoré sme použili. Ak však do nášho kódu pridáme dokumentačný reťazec, pre ostatných vývojárov bude ľahké porozumieť kódu bez toho, aby museli študovať viac o funkciách. Nie sme obmedzení na pridávanie komentárov do určitých limitov; komentáre môžu mať jeden alebo viac riadkov. Do kódu ho možno pridať aj viackrát. Potom importujte NumPy ako np.
'''Vytvorenie premennej, do ktorej prenesieme pole veľkosti 1x6'''pole = napr. pole ( [ jedenásť , 22 , 33 , 44 , 55 , 66 ] )
'''priradenie poľa k funkcii tofile(), aby sa uložilo do súboru s názvom arr'''
pole . vyplniť ( 'arr.bin' )
'''zobraziť súbor pomocou funkcie fromfile'''
vytlačiť ( napr. zo súboru ( 'arr.bin' , dtype = int ) )
Ako je uvedené v nasledujúcom úryvku, reťazce dokumentov sa vo výstupe nezobrazujú, čo znamená, že to neovplyvňuje výstup ani kompiláciu kódu. Dokumentačné reťazce sú počas procesu kompilácie ignorované.
Záver
V tejto príručke sme sa dozvedeli o dokumentačných reťazcoch v NumPy. Porovnali sme dokumenty s komentármi a vysvetlili sme rozdiel medzi nimi. Naučili sme sa syntax docstringov a ako ich písať v našom kóde. Ďalej sme sa pomocou príkladov snažili vysvetliť, čo sú to docstringy v NumPy a ako fungujú. Nakoniec sme poznamenali, že sú nevyhnutné pre kóderov. Nebudeme opakovať dôležitosť dokumentačných reťazcov v NumPy. Povieme len, že by ste mali vo svojom kóde použiť docstrings. V NumPy je štýl písania docstringov najobľúbenejší. Je široko používaný v programátorskej komunite, aby sa navzájom informovali o fungovaní a funkčnosti svojich kódov. Táto príručka vám pomôže začať s dokumentačnými reťazcami NumPy. Snažili sme sa pokryť väčšinu toho, čo budete potrebovať, pomocou dokumentačných reťazcov v NumPy.