Protože již víme, jak psát víceřádkové komentáře, můžeme použít buď trojité jednoduché uvozovky, nebo trojité dvojité uvozovky. Dokumentační řetězec používáme, když chceme popsat naše funkce, abychom dokumentaci mohli získat, když ji potřebujeme. Některá IDE vám poskytují dokumentaci pouhým najetím na název a některá zvýrazní určitá klíčová slova. Faktem ale je, že docstrings v NumPy jsou mnohem flexibilnější než v jiných jazycích. Docstring je řetězcový literál, který se vyskytuje na začátku definice funkce. Při používání docstringů v případech funkcí, tříd atd. musíme poskytnout konkrétní hodnoty.
Při použití docstrings s funkcemi musíme předat argumenty. Při jejich použití s třídami předáváme atributy a metody. V případě modulů musíme poskytnout seznam tříd a funkcí. V případě balíčku předáme seznam modulů s funkčností. Takže v podstatě účelem docstring je, jak název vysvětluje, že pomáhá s dokumentací našeho kódu. Děláme dokumentaci tak, že pokud někdo použije náš kód v budoucnu, bude schopen porozumět našemu kódu a logice našeho kódu pomocí docstringu. Vestavěné funkce také obsahují docstrings; můžeme použít funkci help(), abychom se podívali na dokumentační řetězec vestavěných funkcí.
Mezi komentáři a dokumentací je několik rozdílů. Komentáře jsou ignorovány interprety, ale docstrings nejsou ignorovány interprety. Paměť je přidělena pro dokumentační řetězce. Komentář je popis kódu, ale na druhou stranu nám docstrings říkají účel kódu.
Syntax:
Syntaxe pro zápis docstrings v NumPy je:
'''Zpráva docstring'''
Nebo
'''Zpráva docstring'''
Vezměte prosím na vědomí, že docstring není funkce nebo metoda, takže nemá správnou syntaxi. Jediná věc, kterou je třeba poznamenat, je, že začínáme docstring třemi jednoduchými uvozovkami nebo třemi dvojitými uvozovkami. Napíšeme svůj popis kódu a zakončíme jej opět třemi jednoduchými uvozovkami nebo třemi dvojitými uvozovkami na konci. Pro docstring není nic povinného psát. Stačí vložit tři jednoduché nebo dvojité uvozovky před a za popis řetězce.
Příklad 1:
Abychom lépe porozuměli docstrings, uveďme příklad. V tomto příkladu po zahrnutí knihovny NumPy jednoduše deklarujeme proměnnou „a“ a další proměnnou „b“. Poté vytvoříme náš docstring, který říká „Přidejme proměnné „a“ a „b“. V našem případě je to snadný příklad, ale pokud je náš kód složitý, kodérovi to hodně pomůže v pochopení kódu. Poté sečteme proměnné „a“ a „b“ a jejich výstupní výsledek uložíme do jiné proměnné, která je „c“. Nakonec vypíšeme hodnotu proměnné „c“. Nyní spustíme náš kód.
import nemotorný tak jako např.A = 1
b = dva
'''Přidejme proměnné aab'''
C = a+b
tisk ( C )
Toto je náš výstup z daného kusu kódu. Vidíme, že systém neuvedl žádnou chybu ohledně nesprávné syntaxe nebo čehokoli pro řádek 7 našeho kódu. Systém také nevytiskl náš dokumentační řetězec. Místo toho pouze vytiskl výstup naší proměnné „c“, ve které jsme řekli našemu systému, aby vytiskl. To ukazuje, jak fungují řetězce dokumentů. Až se příště nový kodér pokusí pracovat na našem kódu, pochopí, co děláme s pomocí našeho docstringu. Nebude však vytištěn jako výstup, takže uživatel kódu nebude rušen.
Příklad 2:
Nyní provedeme komplexní příklad, abychom pochopili fungování dokumentačního řetězce. Nejprve zahrneme knihovnu NumPy a poté napíšeme řetězec doc, ve kterém vysvětlíme další řádek kódu, kde vysvětlíme inicializaci pole. Do druhé části kódu také přidáme docstrings. Nyní, pokud sdílíme tento kód s jakýmkoli novým vývojářem Pythonu, aniž bychom přidali docstring, bude pro něj nějak obtížné znát fungování a účel tohoto kódu. Musí nejprve vyhledat funkce, které jsme použili. Pokud však do našeho kódu přidáme docstring, bude pro ostatní vývojáře snadné porozumět kódu, aniž by museli více studovat funkce. Nejsme omezeni na přidávání komentářů do určitých limitů; komentáře mohou mít jeden nebo více řádků. Může být také přidán více než jednou do kódu. Poté importujte NumPy jako np.
'''Vytvoření proměnné, které předáme pole o velikosti 1x6'''pole = např. pole ( [ jedenáct , 22 , 33 , 44 , 55 , 66 ] )
'''přiřazení pole funkci tofile(), aby bylo uloženo do souboru s názvem arr'''
pole . tofile ( 'arr.bin' )
'''zobrazit soubor pomocí funkce fromfile'''
tisk ( např. ze souboru ( 'arr.bin' , dtype = int ) )
Jak je ukázáno v následujícím úryvku, docstrings se ve výstupu nezobrazují, což znamená, že to neovlivňuje výstup nebo kompilaci kódu. Dokumentační řetězce jsou během kompilace ignorovány.
Závěr
V této příručce jsme se dozvěděli o dokumentačních řetězcích v NumPy. Porovnali jsme dokumenty s komentáři a vysvětlili rozdíl mezi nimi. Naučili jsme se syntaxi docstrings a jak zapsat docstrings v našem kódu. Dále jsme se také pomocí příkladů pokusili vysvětlit, co jsou docstring v NumPy a jak fungují. Nakonec jsme poznamenali, že jsou pro kodéry nezbytné. Nebudeme opakovat důležitost dokumentačních řetězců v NumPy. Řekneme jen, že byste měli ve svém kódu použít docstrings. V NumPy je styl psaní docstringů nejoblíbenější. Je široce používán v programátorské komunitě, aby se navzájem informovali o práci a funkčnosti svých kódů. Tato příručka vám pomůže začít s NumPy docstrings. Snažili jsme se pokrýt většinu toho, co budete potřebovat, pomocí docstrings v NumPy.