Документация по Python

Комментарии и документация кода

В: Документация по Python

Введение

Примеры

Однострочные, встроенные и многострочные комментарии

Комментарии используются для объяснения кода, когда сам основной код неясен.

Python игнорирует комментарии, и поэтому не будет выполнять код там или вызывать синтаксические ошибки для простых английских предложений.

Однострочные комментарии начинаются с хэш - символом ( # ) и заканчиваются в конце строки.

  • Однострочный комментарий:
 # This is a single line comment in Python

 
  • Встроенный комментарий:
 print("Hello World")  # This line prints "Hello World"

 
  • Комментарии охватывающих несколько строк есть """ или ''' . На обоих концах Это то же самое , как многострочные строки, но они могут быть использованы в качестве комментариев:
 """
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
""" 

Программный доступ к строкам документов

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

Пример функции

 def func():
    """This is a function that does nothing at all"""
    return

 

Строка документации можно получить с помощью __doc__ атрибута:

 print(func.__doc__)

 

Эта функция вообще ничего не делает

 help(func)

 

Справка по функции func в модуле __main__ :

func()

Эта функция вообще ничего не делает

Еще один пример функции

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

 def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`

    Optional parameter `greeting` can change what they're greeted with."""

    print("{} {}".format(greeting, name))
 

помощь (приветствовать)

Справка по функции greet в модуле __main__ :

greet(name, greeting='Hello')

Печать приветствие пользователя name \ Необязательный параметр greeting может изменить то , что они встречали с.

Преимущества строк документации перед обычными комментариями

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

 def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.

    print("{} {}".format(greeting, name))
 

печать (здороваться. документ)

Никто

 help(greet)

 

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

greet(name, greeting='Hello')

Написать документацию, используя строки документации

Строка документация является многострочным комментарий используется для документирования модулей, классов, функции и методы. Это должно быть первое утверждение компонента, который он описывает.

 def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)
 
 class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

 

Значение строки документации можно получить доступ в программе и - например - используется в help команде.

Синтаксические соглашения  ОПТОСОЗ 257

PEP 257 определяет стандарт синтаксиса для комментариев строки документации. Это в основном позволяет два типа:

  • Однострочные строки документов:

Согласно PEP 257 они должны использоваться с короткими и простыми функциями. Все помещается в одну строку, например:

 def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

 

Строка документа должна заканчиваться точкой, глагол должен быть в императивной форме.

  • Многострочные строки документов:

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

 def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

 

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

Примечание PEP 257 определяет , какая информация должна быть предоставлена в строку документации, она не определяет , в каком формате она должна быть предоставлена. Это послужило причиной для других партий и документации разборе инструментов указать свои собственные стандарты в отношении документации, некоторые из которых перечислены ниже , и в этом вопросе .  сфинкс

Sphinx является инструментом для генерации HTML на основе документации для проектов , основанных на Python строки документации. Его язык разметки используется ReStructuredText . Они определяют свои собственные стандарты в отношении документации, pythonhosted.org Саваофа очень хорошее описание их . Формат сфинкса представляет собой, например , используемую PyCharm IDE .

Функция будет документирована следующим образом в формате Sphinx / reStructuredText:

 def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

 

Руководство по стилю Google Python

Google опубликовал Google Python Style Guide , который определяет соглашение кодирования для Python, включая комментарии к документации. По сравнению с Sphinx / reST многие говорят, что документация в соответствии с рекомендациями Google лучше читается человеком.

Страница pythonhosted.org упоминалось выше , также приведены некоторые примеры для хорошей документации в соответствии с Руководстве по стилю Google.

Используя Наполеона плагин, Sphinx может также анализировать документацию в Google Style Guide-совместимый формат.

Функция будет документирована следующим образом в формате руководства по стилю Google:

 def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4

 

Синтаксис

Параметры

Примечания

Еще от кодкамп
Замечательно! Вы успешно подписались.
Добро пожаловать обратно! Вы успешно вошли
Вы успешно подписались на кодкамп.
Срок действия вашей ссылки истек.
Ура! Проверьте свою электронную почту на наличие волшебной ссылки для входа.
Успех! Ваша платежная информация обновлена.
Ваша платежная информация не была обновлена.