Строка документации NumPy

Поскольку мы уже знаем, как писать многострочные комментарии, мы можем использовать либо тройные одинарные кавычки, либо тройные двойные кавычки. Мы используем строку документации, когда хотим описать наши функции, чтобы мы могли получить документацию, когда она нам понадобится. Некоторые IDE предоставляют документацию, просто наведя указатель мыши на имя, а некоторые выделяют определенные ключевые слова. Но дело в том, что строки документации в NumPy гораздо более гибкие, чем в других языках. Docstring — это строковый литерал, который появляется в начале определения функции. Мы должны указать определенные значения при использовании строк документации в случаях функций, классов и т. д.

При использовании строк документации с функциями мы должны передавать аргументы. При использовании их с классами мы передаем атрибуты и методы. В случае с модулями мы должны предоставить список классов и функций. В случае с пакетом мы передаем список модулей с функциональностью. Таким образом, основная цель строки документации, как понятно из названия, состоит в том, чтобы помочь с документированием нашего кода. Мы делаем документацию, чтобы, если кто-то будет использовать наш код в будущем, он смог понять наш код и логику нашего кода с помощью docstring. Встроенные функции также содержат строки документации; мы можем использовать функцию help() для просмотра строки документации встроенных функций.

Есть несколько различий между комментариями и строками документации. Комментарии игнорируются интерпретаторами, но строки документации не игнорируются интерпретаторами. Память выделяется для docstrings. Комментарий — это описание кода, но, с другой стороны, строки документации говорят нам о назначении кода.

Синтаксис:

Синтаксис для записи строк документации в NumPy:

Обратите внимание, что строка документации не является функцией или методом, поэтому у нее нет правильного синтаксиса. Единственное, что здесь следует отметить, это то, что мы начинаем строку документации с трех одинарных или трех двойных кавычек. Мы пишем наше описание кода и снова заканчиваем его тремя одинарными или тремя двойными кавычками в конце. Нет ничего обязательного для написания строк документации. Вам просто нужно поставить три одинарных или двойных кавычки до и после описания строки.

Пример 1:

Чтобы лучше понять строки документации, давайте рассмотрим пример. В этом примере после включения библиотеки NumPy мы просто объявляем переменную «a» и еще одну переменную «b». После этого мы создаем нашу строку документации, в которой говорится: «Давайте добавим переменные «a» и «b». В нашем случае это простой пример, но если наш код сложный, это очень помогает программисту понять код. После этого мы суммируем переменные «a» и «b» и сохраняем их результат вывода в другой переменной, которой является «c». Наконец, мы печатаем значение переменной «c». Теперь мы выполняем наш код.

Это наш вывод из данного фрагмента кода. Мы видим, что система не выдала ни одной ошибки о неправильном синтаксисе или чего-либо еще для строки 7 нашего кода. Кроме того, система не напечатала нашу строку документации. Вместо этого он напечатал только вывод нашей переменной «c», в котором мы сказали нашей системе печатать. Это показывает, как работают строки документации. В следующий раз, когда новый кодер попытается работать с нашим кодом, он поймет, что мы делаем с помощью нашей строки документации. Но он не будет напечатан как вывод, поэтому пользователя кода это не побеспокоит.

Пример 2:

Теперь мы выполняем сложный пример, чтобы понять работу строки документации. Сначала мы включаем библиотеку NumPy, а затем пишем строку документа, в которой мы объясняем следующую строку кода, где мы объясняем инициализацию массива. Мы также добавляем строки документации в другую часть кода. Теперь, если мы поделимся этим кодом с любым новым разработчиком Python, не добавляя строки документации, ему будет трудно узнать, как работает и зачем этот код. Он должен искать сначала о функциях, которые мы использовали. Но если мы добавим строку документации в наш код, другим разработчикам будет легко понять код, не изучая дополнительные функции. Мы не ограничены добавлением комментариев в некоторых пределах; комментарии могут состоять из одной или нескольких строк. Его также можно добавить в код более одного раза. Затем импортируйте NumPy как np.

Как показано в следующем фрагменте, строки документации не отображаются в выводе, что означает, что это не влияет на вывод или компиляцию кода. Строки документации игнорируются в процессе компиляции.

Вывод

В этом руководстве мы узнали о строках документации в NumPy. Мы сравнили строки документации с комментариями и объяснили разницу между ними. Мы изучили синтаксис строк документации и то, как писать строки документации в нашем коде. Кроме того, мы также попытались объяснить, что такое строки документации в NumPy и как они работают, с помощью примеров. Наконец, мы отметили, что они необходимы для кодеров. Мы не будем повторять важность строк документации в NumPy. Мы просто скажем, что вы должны использовать строки документации в своем коде. В NumPy стиль написания строк документации является наиболее популярным. Он широко используется в сообществе программистов, чтобы сообщать друг другу о работе и функциональности их кодов. Это руководство поможет вам начать работу со строками документации NumPy. Мы попытались охватить большую часть того, что вам понадобится, используя строки документации в NumPy.