В PHP я привык к синтаксису PHPdoc:
/** Do something useful
@param first Primary data
@return int
@throws BadException
*/
function($first){ ...
- своего рода короткая полезная ссылка: очень удобно, когда все, что вам нужно, это просто вспомнить «что это?», Особенно для сторонних библиотек. Кроме того, все IDE могут отображать это во всплывающих подсказках.
Кажется, что в Python нет соглашений: просто текст. Это хорошо описывает вещи, но это слишком долго, чтобы быть дайджестом.
Хорошо, пусть будет так. Но в своих приложениях я не хочу использовать стопки открытого текста.
Существуют ли известные соглашения, которым нужно следовать? А как документировать атрибуты класса ?! PyCharm IDE рецепты особенно приветствуются:)
В Python3 есть PEP 3107 для функциональных аннотаций. Это не полезно для 2.x (2.6, в частности)
Также есть PEP 0287 для reStructuredText: причудливый, но все еще не структурированный.