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

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

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

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

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

 
def sum(x, y):
  """Returns arg1 value add to arg2 value."""
  return a+b
print sum.__doc__

Вывод:

 
Returns arg1 value add to arg2 value.

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

Пример

 
def generic_socket(param1, param2):
    """
    Summary generic_socket.
    Extended description of generic_socket.
    Parameters
    ----------
    param1 : int
        Description of param1 (port)
    param2 : str
        Description of param2 (ipaddress)
    Returns
    -------
    int
        Description of return value
    """
    return 42

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

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

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

(Пока оценок нет)