При документировании кода Python с помощью doxygen вы должны документировать собственные параметры?

Question

У меня есть некоторый код Python, который был задокументирован с помощью doxygen, и я хотел бы знать, нормально ли это документировать собственные параметры для методов?

Пример:

## @par Description:
# Some desc
# @note 
#     
# @param something @e string: a string
#    
# @return @b Boolean: True if ...  
#
# @b Example:
# @code
#
#    instance.myMethod("some")
#
# @endcode
def myMethod(self, something):
    return True

Какая документация по доксигену будет правильной для этого метода?

Должен ли я сделать что-то особенное в отношении параметра self?

Как мне документировать типы параметров, такие как string, int, list, ...?

Answer 1

Я не знаю, что такое обычная практика, но я бы этого не делал. Это просто добавляет беспорядок в документы, так как его использование очевидно. Беспорядок в документации плох, потому что он скрывает то, что вы действительно хотите увидеть.