Attualmente sto iniziando con Python e ho un forte background in PHP e in PHP ho preso l'abitudine di usarlo javadoc
come modello di documentazione.
Mi chiedevo se javadoc
ha il suo posto come docstring
documentazione in Python. Quali sono le convenzioni stabilite e / o le corporazioni ufficiali qui?
Ad esempio, qualcosa del genere è troppo elaborato per adattarsi alla mentalità di Python o dovrei cercare di essere il più conciso possibile?
"""
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
"""
E se sono un po 'troppo esaustivo, dovrei scegliere qualcosa del genere (dove la maggior parte della documentazione non viene stampata con il __doc__
metodo)?
# 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)