Что такое docstring в Python?

Строки документации Python (или docstrings) обеспечивают удобный способ связывания документации с модулями, функциями, классами и методами Python. Как вы можете видеть, даже для относительно простой функции документирование использования комментариев быстро делает его неприятным и трудным для чтения. Итак, чтобы решить эту проблему, была введена докшрина. Docstring - это просто многострочная строка, которая не привязана ни к чему. Он указан в исходном коде, который используется для документирования определенного сегмента кода. В отличие от обычных комментариев исходного кода, docstring должна описывать, что делает функция, а не как.

У всех модулей обычно должны быть docstrings, и все функции и классы, экспортируемые модулем, также должны иметь docstrings. У общедоступных методов (включая конструктор __init__) также должны быть docstrings. Пакет может быть задокументирован в docstring модуля файла __init__.py в каталоге пакета.

Однострочные Docstrings

Однострочники для действительно очевидных случаев. Они должны поместиться на одной линии. В зависимости от сложности выполняемой функции, метода или класса однострочная документальная строка может быть совершенно подходящей. Они обычно используются для действительно очевидных случаев, таких как:

Вывод:

Однако в более крупных или более сложных проектах часто бывает полезно дать больше информации о функции, о том, что она делает, о любых исключениях, которые она может поднять, о том, что она возвращает, или о соответствующих деталях параметров. Для более подробной документации кода популярным является стиль, используемый для проекта Numpy, который часто называют docstrings стиля Numpy.

Пример

Плагин sphinx.ext.napoleon позволяет Sphinx анализировать этот стиль docstrings, что упрощает включение в текст проекта docstrings в стиле NumPy.

Документ должен описывать функцию таким образом, чтобы ее было легко понять. Такие инструменты, как Sphinx, будут анализировать ваши docstrings как reStructuredText и корректно отображать его как HTML. Это позволяет легко вставлять фрагменты кода примера в документацию проекта. Большинство документов Python написано с помощью reStructuredText. Это похоже на Markdown со всеми дополнительными расширениями, встроенными. Однако docstrings кажутся гораздо более личными, чем другие области кода. У разных проектов будет свой собственный стандарт.

Источник: http://net-informations.com/python/iq/docstring.htm

1 Звезда2 Звезды3 Звезды4 Звезды5 Звезд (Пока оценок нет)

Add a Comment

Ваш e-mail не будет опубликован. Обязательные поля помечены *