Вот бы еще кто подсказал аналог phpDoc комментария "@property Bar1 bar1" для автокомплита в PyCharm.
Docutils, Pycharm умеет её анализировать. Разметка там в нормальном RestructuredText. Плюс, есть отличная система документации Sphinx.
Вот пример оформления docstring для функции:
def public_fn_with_sphinxy_docstring(name, state=None):
"""This function does something.
:param name: The name to use
:type name: str
:param state: Current state to be in
:type state: bool
:returns: the return code
:rtype: int
:raises: AttributeError, KeyError
"""
return 0
Или, более компактно:
def public_fn_with_sphinxy_docstring(name, state=None):
"""This function does something.
:param str name: The name to use
:param bool state: Current state to be in
:returns: int - the return code
:raises: AttributeError, KeyError
"""
return 0
Кроме того, в 3-й ветке питона есть
поддержка аннотаций типов (можно указывать тип аргументов функции и возвращаемый тип). Pycharm это тоже понимает.