Uso de javadoc para la documentación de Python [cerrado]

Actualmente estoy comenzando con Python y tengo una sólida experiencia en PHP y en PHP me he acostumbrado a usar javadoccomo plantilla de documentación.

Me preguntaba si javadoctiene su lugar como docstringdocumentación en Python. ¿Cuáles son las convenciones establecidas y / o las líneas de responsabilidad oficiales aquí?

Por ejemplo, ¿algo así es demasiado elaborado para adaptarse a la mentalidad de Python o debería tratar de ser lo más conciso posible?

"""
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
"""

Y si soy demasiado exhaustivo, ¿debería elegir algo como esto (donde la mayoría de la documentación no se imprime a través del __doc__método)?

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

Eche un vistazo al formato reStructuredText (también conocido como "reST"), que es un formato de marcado de texto sin formato / cadena de documentación, y probablemente el más popular en el mundo de Python. Y sin duda debería mirar a Sphinx , una herramienta para generar documentación a partir de reStructuredText (utilizada, por ejemplo, para la documentación de Python). Sphinx incluye la posibilidad de extraer documentación de las cadenas de documentos en su código (vea sphinx.ext.autodoc ), y reconoce las listas de campos reST siguiendo ciertas convenciones. Esto probablemente se ha convertido (o se está convirtiendo) en la forma más popular de hacerlo.

Su ejemplo podría verse de la siguiente manera:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

O extendido con información de tipo:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

Siga la Guía de estilo de Google Python . Tenga en cuenta que Sphinx también puede analizar este formato utilizando la extensión Napolean , que vendrá empaquetada con Sphinx 1.3 (esto también es compatible con PEP257 ):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

Ejemplo tomado de la documentación napoleana vinculada anteriormente.

Un ejemplo completo sobre todos los tipos de cadenas de documentos aquí .

El estándar para las cadenas de documentación de Python se describe en Python Propuesta de Mejora de Python 257 .

El comentario apropiado para su método sería algo así como

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """

Echa un vistazo a Documenting Python , una página "dirigida a autores y posibles autores de documentación para Python".

En resumen, reStructuredText es lo que se usa para documentar Python. La guía del desarrollador contiene una cartilla reST, una guía de estilo y consejos generales para escribir buena documentación.