Я ищу лучшие практики для документации по функциям/классу/модулю, т.е. комментарии в самом коде. В идеале я бы хотел создать шаблон комментария, который будет доступен для чтения и использования человеком с помощью утилит документации Python.
Я прочитал документацию Python для docstrings.
Я понимаю эту часть:
В первой строке всегда должно быть краткое краткое изложение цели объектов. Для краткости он не должен явно указывать имя или тип объектов, поскольку они доступны другими средствами (за исключением того, что имя является глаголом, описывающим операцию функций). Эта строка должна начинаться с заглавной буквы и заканчиваться периодом.
Если в строке документации больше строк, вторая строка должна быть пустой, визуально отделяя итоговую информацию от остальной части описания.
Это предложение нуждается в более подробном объяснении:
Следующие строки должны содержать один или несколько абзацев, описывающих соглашения об объектах, их побочные эффекты и т.д.
В частности, я ищу примеры хорошо прокомментированных функций и классов.