Ponieważ wiemy już, jak pisać komentarze wielowierszowe, możemy użyć potrójnych pojedynczych cudzysłowów lub potrójnych podwójnych cudzysłowów. Używamy ciągu dokumentacji, gdy chcemy opisać nasze funkcje, abyśmy mogli uzyskać dokumentację, kiedy jej potrzebujemy. Niektóre IDE dostarczają dokumentacji, po prostu najeżdżając kursorem na nazwę, a niektóre podświetlają określone słowa kluczowe. Ale faktem jest, że dokumenty w NumPy są o wiele bardziej elastyczne niż w innych językach. Docstring to literał ciągu, który występuje na początku definicji funkcji. Musimy podać konkretne wartości podczas korzystania z docstringów w przypadku funkcji, klas itp.
Używając docstringów z funkcjami, musimy przekazać argumenty. Używając ich z klasami, przekazujemy atrybuty i metody. W przypadku modułów musimy podać listę klas i funkcji. W przypadku pakietu przekazujemy listę modułów z funkcjonalnością. Tak więc w zasadzie celem docstring jest, jak sama nazwa wskazuje, pomoc w dokumentacji naszego kodu. Robimy dokumentację, aby jeśli ktoś w przyszłości użyje naszego kodu, będzie mógł zrozumieć nasz kod i logikę naszego kodu za pomocą docstringu. Wbudowane funkcje również zawierają w sobie dokumenty; możemy użyć funkcji help(), aby przejrzeć ciąg dokumentów wbudowanych funkcji.
Istnieje kilka różnic między komentarzami a dokumentacją. Komentarze są ignorowane przez tłumaczy, ale napisy nie są ignorowane przez tłumaczy. Pamięć jest przydzielana na łańcuchy dokumentacyjne. Komentarz jest opisem kodu, ale z drugiej strony napisy dokumentacyjne informują nas o celu kodu.
Składnia:
Składnia zapisu dokumentów w NumPy to:
'''Wiadomość dokumentu'''
Lub
'''Wiadomość dokumentu'''
Należy pamiętać, że docstring nie jest funkcją ani metodą, więc nie ma właściwej składni. Jedyną rzeczą, na którą należy zwrócić uwagę, jest to, że dokument docstring zaczynamy od trzech pojedynczych cudzysłowów lub trzech podwójnych cudzysłowów. Piszemy nasz opis kodu i kończymy go ponownie trzema pojedynczymi cudzysłowami lub trzema podwójnymi cudzysłowami na końcu. Nie ma obowiązkowej rzeczy do napisania dla dokumentów. Musisz tylko umieścić trzy pojedyncze lub podwójne cudzysłowy przed i po opisie ciągu.
Przykład 1:
Aby lepiej zrozumieć ciągi dokumentacyjne, zróbmy przykład. W tym przykładzie po dołączeniu biblioteki NumPy po prostu deklarujemy zmienną „a” i kolejną zmienną „b”. Następnie tworzymy nasz dokument, który mówi „Dodajmy zmienne „a” i „b”. W naszym przypadku jest to prosty przykład, ale jeśli nasz kod jest złożony, bardzo pomaga to koderowi w zrozumieniu kodu. Następnie sumujemy zmienne „a” i „b” i przechowujemy ich wynik wyjściowy w innej zmiennej, którą jest „c”. Na koniec wypisujemy wartość zmiennej „c”. Teraz wykonujemy nasz kod.
import numpy jak npa = 1
b = dwa
'''Dodajmy zmienne a i b'''
c = a+b
wydrukować ( c )
To jest nasze wyjście z podanego fragmentu kodu. Widzimy, że system nie podał żadnego błędu o niepoprawnej składni ani niczego dla linii 7 naszego kodu. Ponadto system nie wydrukował naszego dokumentu. Zamiast tego wypisał tylko wyjście naszej zmiennej „c”, w której kazaliśmy naszemu systemowi drukować. To pokazuje, jak działają dokumenty. Następnym razem, gdy nowy programista spróbuje pracować nad naszym kodem, zrozumie, co robimy za pomocą naszego docstringu. Ale nie zostanie wydrukowany jako wynik, więc użytkownik kodu nie będzie przez to niepokojony.
Przykład 2:
Teraz przedstawimy skomplikowany przykład, aby zrozumieć, jak działa dokumentacja. Najpierw dołączamy bibliotekę NumPy, a następnie piszemy ciąg dokumentacyjny, w którym wyjaśniamy kolejny wiersz kodu, w którym wyjaśniamy inicjalizację tablicy. Dodajemy również docstringi w drugiej części kodu. Teraz, jeśli udostępnimy ten kod nowemu programiście Pythona bez dodawania dokumentów, będzie mu w jakiś sposób trudno poznać działanie i cel tego kodu. Musi najpierw poszukać funkcji, z których korzystaliśmy. Ale jeśli dodamy do naszego kodu docstring, inni programiści z łatwością zrozumieją kod bez zagłębiania się w funkcje. Nie ograniczamy się do dodawania komentarzy do pewnych limitów; komentarze mogą mieć jedną lub więcej niż jedną linię. Można go również dodać więcej niż raz w kodzie. Następnie zaimportuj NumPy jako np.
'''Tworzenie zmiennej do której przekażemy tablicę o rozmiarze 1x6'''szyk = np. szyk ( [ jedenaście , 22 , 33 , 44 , 55 , 66 ] )
'''przypisanie tablicy do funkcji tofile(), aby umożliwić jej zapisanie w pliku o nazwie arr'''
szyk . do pliku ( „arr.bin” )
'''wyświetl plik używając funkcji fromfile'''
wydrukować ( np. z pliku ( „arr.bin” , dtype = int ) )
Jak pokazano w poniższym fragmencie, ciągi dokumentacyjne nie są wyświetlane w danych wyjściowych, co oznacza, że nie mają one wpływu na dane wyjściowe ani kompilację kodu. Docstrings są ignorowane podczas procesu kompilacji.
Wniosek
W tym przewodniku dowiedzieliśmy się o dokumentach w NumPy. Porównaliśmy dokumenty z komentarzami i wyjaśniliśmy różnicę między nimi. Poznaliśmy składnię dokumentów i jak je pisać w naszym kodzie. Ponadto staraliśmy się również wyjaśnić, czym są dokumenty w NumPy i jak działają na przykładach. Na koniec zauważyliśmy, że są one niezbędne dla programistów. Nie będziemy powtarzać znaczenia dokumentów w NumPy. Powiemy tylko, że powinieneś użyć w swoim kodzie dokumentów docstrings. W NumPy najpopularniejszy jest styl pisania dokumentów. Jest szeroko stosowany w społeczności programistów, aby informować się nawzajem o działaniu i funkcjonalności ich kodów. Ten przewodnik pomoże Ci rozpocząć pracę z dokumentacją NumPy. Staraliśmy się pokryć większość potrzebnych informacji za pomocą dokumentacji w NumPy.