Przykład Python Docstring

Python dokumentacji, często znane jako Docstrings, są literałami łańcuchowymi używanymi w deklaracji modułu, klasy, metody lub funkcji. Dowolny atrybut DOC obiektu Pythona (__doc__), a także wbudowana funkcja funkcji help (), zapewnia dostęp do dokumentów. Jako pierwsze zdanie w definicji obiektu stała ciągów określa dokument obiektu. Python Docstrings jest omówiony w tej sesji. Za pomocą kilku przykładów odkryjemy dokładne zastosowanie dokumentów.

Podczas gdy komentarze są wykorzystywane do programów, stwierdzeń i wyrażeń, które są zazwyczaj krótkie, dokumenty są doskonałe do zrozumienia funkcjonowania większej części skryptu, takich jak ogólne użycie dowolnego modułu, klasy lub funkcji. Są opisem wiersza kodu lub instrukcji wyprodukowanej przez programistę, który zwykle jest dla siebie, aby zrozumieć, co robi. Ważne jest, aby poprawnie udokumentować kod, jeśli chcesz pisać programy z jasnym kodem i dobrą dokumentacją. Dokumenty są dostarczane, stosując „potrójne pojedyncze cytaty” lub „potrójne podwójne cytaty” zaraz po definicji funkcji, klasy lub metody.

Przykład 1: Program Python Docstring Triple Single Quotes

Albo metodę __doc__ obiektu lub funkcję pomocy można użyć do uzyskania dokumentów. Deklaracja i użycie dokumentu z potrójnymi pojedynczymi cytatami pokazano w następujących przykładach:

Zacznij od zdefiniowania funkcji w Pythonie. Stworzymy funkcję jako my_func (). W ramach ciała MY_FUNC mamy jako dokument owinięty wokół potrójnych pojedynczych cytatów. Następnie, na końcu funkcji, wyraźnie wykonujemy instrukcję zwrotu, która zwraca wartość Brak. Funkcja drukowania przyjmuje my_func z obiektem _doc_, który wyświetli dokument. Ponadto mamy funkcję pomocy w Python, która służy do drukowania dokumentacji funkcji MY_FUNC.

Gdy ten konkretny program jest debugowany i uruchomiony, generuje następujące wyniki na ekranie konsoli Spyder:

Przykład 2: Program Python Docstring Triple Cytaty

Poniższy kod wdraża deklarację DocString i używa się z potrójnymi podwójnymi kwotami:

Tutaj podajemy nazwę funkcji my_func2. Wewnątrz ciała MY_FUNC2 deklarujemy dokument z potrójnym podwójnym cytatem. Następnie wywołujemy obiekt Pythona _doc_, aby wydrukować określony dokument i dokumentację funkcji my_func2 z funkcją pomocy.

Wyniki generowane z wyżej wymienionych kodów są następujące. To wyjście jest generowane przez wykonanie poprzedniego kodu umieszczonego w Spyder:

Przykład 3: Program Python One-Line Docstring

Jedno-line dokumenty są właśnie tym, co sugeruje ich nazwa: jedna linia. Są zatrudnieni w rażących sytuacjach. Ostatnie cytaty znajdują się na podobnej linii jak początkowe. Dla jedno-linii wydaje się to bardziej atrakcyjne.

Tutaj konstruujemy funkcję jako „dodaj”, która przyjmuje dwa argumenty: x i y. Następnie deklarujemy jednoliniową dokument wewnątrz ciała definicji funkcji „dodaj”. Instrukcja zwrotna zwraca wartość z dodania dwóch wartości. Instrukcja drukowania jest wywoływana do wyświetlania DOCSTRING wewnątrz funkcji Add za pomocą obiektu _doc_.

Wyniki jednoladowego DocString pokazano na następnym ekranie konsoli Spyder. Wyjście to jest generowane przez wykonanie powyższego kodu umieszczonego w Spyder:

Przykład 4: Program wielopoziomowego dokumentu Python

Podobnie jak jednoliniowe Docstrings, wielozadaniowe dokumenty rozpoczynają. Linia podsumowania może pojawić się na podobnej linii jak cytaty początkowe lub na innej linii. Docstring wielopoziomowy pokazano w następującym przypadku:

W tym konkretnym przykładowym skrypcie mamy definicję funkcji, która ma nazwę jako Python_Function. Ta funkcja ma wartość argumentu x. Ciało funkcyjne jest zadeklarowane za pomocą łańcucha wielu linii, która jest opisem wartości argumentu i typu danych int. Następnie zdefiniowano polecenie powrotu. Docstring multiline jest wyświetlany przez wywołanie obiektu _doc_ wewnątrz funkcji drukowania.

Multi-liny DocString są wydrukowane na terminalu Spyder w następujący sposób:

Przykład 5: Program wgłębienia Python Docstring

Cytaty na początkowej linii są wcięte w tej samej ilości co reszta DocString. Każde wcięcie w pierwszym wierszu DocString (w górę z pierwszą nową linią) jest niepotrzebne i powinno zostać wyeliminowane. Następnie linie w Docstring zachowują swoje względne wcięcie. Jako ilustrację, jak utworzyć dokumenty dla klasy i jej metod, spójrzmy na przykład. Dostęp do DocString jest poprzez pomoc:

Definiujemy klasę z klasą słów kluczowych i nazywamy tę klasę jako my_python_example. W ramach klasy My_Python_Example deklarujemy dokument otoczony potrójnymi podwójnymi kwotami. Następnie tworzymy kwadrat funkcji, który ma wejście x, a funkcja jest również zadeklarowana za pomocą DocString. Następnie tworzymy inną funkcję o nazwie, Cube. Wymaga również wejścia n. Ta funkcja jest tworzona dla kostki liczby. To stwierdzenie jest wyjaśnione przez DocString Deklaracja. Następnie mamy funkcję pomocy w Pythonie, aby wykonać dokumentację klasy my_python_program i kwadrat funkcji.

Z wspomnianego wcześniej programu Pythona uzyskuje się następujące wymienione dane wyjściowe. To wyjście jest generowane przez wykonanie wcześniej przymocowanego kodu w Spyder:

Wniosek

Głównym celem tego kursu jest zapoznanie się z dokumentami poprzez przeglądanie podstawowych pomysłów. Ponieważ jednak Docstrings jest tak szerokim tematem, możliwe jest, że niektóre pomysły zostały pominięte. Aby uzyskać dokumentację funkcji, użyj funkcji help (). Umieść ciąg, albo ciąg jednowarstwowy lub ciąg wieloletni, w pierwszym wierszu funkcji, aby dodać dokumentację.