Как Pythonic создает информативные комментарии в Python 2.x?

Question

Для дальнейшего пояснения, C # имеет директиву ///, которая вызывает комментарии в сверхсекретном стиле, которые позволяют вам встроить красивые комментарии в intellisense.В Java есть директива '@', которая также позволяет вам получать хорошие комментарии.

Есть ли в Python что-то подобное?Надеюсь, этот вопрос достаточно ясен, спасибо!

Answer 1

Они называются строк документации в Python. См. Документацию .

Приятной особенностью являются примеры кода ( объяснено здесь ). Они позволяют поставить код в документации:

>>> 1 + 1
2
>>>

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

Answer 2

Соглашение хорошо документировано в PEP 257 .

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

Также естьнекоторую историю, которую стоит прочитать, если у вас есть время в PEP 256 .

Answer 3

В Python нет «инструмента» для генерации документации.Один из доступных инструментов, которые я могу порекомендовать, это epydoc .Он поддерживает такие директивы, как @type, @param, @rtype, @returns и @raises.На сайте также есть несколько примеров.

Answer 4

, как другие люди указывали в Python, ресурс, который вы ищете, называется строкой документа. другие люди предложили прочитать документацию, alibeit Я предлагаю посмотреть эту ссылку

Sphinx Project , это такая система, как Sand Castle, которая помогает вам создавать и разрабатывать документацию, эта документация может быть создана из строки документа, но не является обязательной.

надеюсь, это поможет

Answer 5

В Python строку документации можно просмотреть с помощью команд.

class myClass:
    """
      This is some documentation for the class.
      method1()
      method2()
    """
    def method1(p1):
        ....
        ...
        ...
    def method2():
        ...
        ...

v = myClass

Затем вы можете просмотреть строку документации, используя

v.__doc__

или

help(myClass)