Как написать справочный/описательный текст для функций Python

Question

Недавно я начал программирование с помощью Python. Я должен написать много функций и задавался вопросом, как я могу включить текст справки или описания, чтобы он отображался в инспекторе объектов spyder при вызове функции. В MatLab это сработало, поместив комментарий в начале файла функции. Есть ли аналогичный метод в Pythong (используя Spyder)?

Answer 1

По умолчанию первая строка в теле метода используется как его docstring (или строка документации). Python будет использовать это, если для этого метода вызывается help().

def foo(bar): 
    ''' Takes bar and does 
     some things to it ''' 
    return bar 

help(foo) 
foo(bar) 
    Takes bar and does 
    some things to it 

Вы можете прочитать больше о том, как это работает, читая PEP-258 и this question входит в некоторые подробности.

Answer 2

(Spyder DEV здесь) Есть другая пара вещей, которые вы должны знать (кроме того, что @ бурхан-Халид упоминается) относительно самого Spyder:

1. Если вы хотите, чтобы ваши строки документации красиво отформатированный в Инспекторе объектов вам необходимо записать их по стандарту numpydoc, который поясняется here. Это набор соглашений, используемых почти всеми научными пакетами python для написания своих докстерий. Это не обязательно, но мы также следуем за ним при преобразовании docstrings (которые приходят в виде обычного текста) в html.

2. Вы должны использовать Ctrl +Я перед именем объекта, чтобы показать свою помощь в инспекторе объектов.