Как правильно писать документацию?

Рейтинг: 4Ответов: 1Опубликовано: 06.03.2023

Я видел в кодах на Python3 документацию следующего типа:

"""
   Документация
"""

Но также я видел что часто пишут что-то типа:

"""
   :name
   Test
   :description
   Description
"""

Как это правильно называется и каков полный список этих меток?

Изменено: Пока самое близкое к ответу я нашёл только тут, тут и тут.

Ответы

▲ 5

Вижу тут дискуссию по теме, которая вроде не должна побуждать к этому.

Я бы начал все таки с официальной документации и PEP257.

В PEP257 определено соглашение, как мы документируем.

Далее, из написанных согласно pep257 строк документации, можно сгенерировать полноценную доку с помощью модуля pydoc.

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

По вашим ссылкам:

  1. Документирование для веб служб, основаных на REST API. Надо понимать, что далеко не каждое приложение подходит под данную технологию
  2. Кастомный способ, написанный для удобства автором ответа (ничего плохого, можно делать все удобства под себя)
  3. Официальная дока для pydoc, упомянутый в ответе.