В настоящее время я начинаю с Python и имею большой опыт работы с PHP, а в PHP я привык использовать javadoc
в качестве шаблона документации.
Мне было интересно, если javadoc
есть свое место в качестве docstring
документации в Python. Каковы здесь установленные соглашения и / или официальные правила?
Например, что-то вроде этого слишком сложное, чтобы вписаться в мышление Python, или я должен стараться быть максимально кратким?
"""
replaces template place holder with values
@param string timestamp formatted date to display
@param string priority priority number
@param string priority_name priority name
@param string message message to display
@return string formatted string
"""
И если я слишком исчерпывающий, я должен пойти с чем-то вроде этого (где большая часть документации не печатается с помощью __doc__
метода)?
# replaces template place holder with values
#
# @param string timestamp formatted date to display
# @param string priority priority number
# @param string priority_name priority name
# @param string message message to display
#
# @return string formatted string
def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
"""
replaces template place holder with values
"""
values = {'%timestamp%' : timestamp,
'%priorityName%' : priority_name,
'%priority%' : priority,
'%message%' : message}
return self.__pattern.format(**values)