Блог

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

Пример:

 ## @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
  

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

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

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

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