español - Usando javadoc para la documentación de Python

python documentation español

Question

Actualmente estoy comenzando con Python y tengo un fuerte conocimiento de PHP y en PHP he tomado el hábito de usar javadoc como una plantilla de documentación.

Me preguntaba si javadoc tiene su lugar como documentación docstring en Python. ¿Hay algo como esto demasiado elaborado para encajar en 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, ¿debo ir con algo como esto en su lugar (donde la mayoría de la documentación no se imprime a través del método __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)

Answer 1

Eche un vistazo a Documentar 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 guía reST, una guía de estilo y consejos generales para redactar una buena documentación.

Answer 2

Eche un vistazo al formato reStructuredText (también conocido como "reST"), que es un formato de texto sin formato / docstring, y probablemente el más popular en el mundo de Python. Y sin duda debe mirar a Sphinx , una herramienta para generar documentación de reStructuredText (utilizado, por ejemplo, para la documentación de Python). Sphinx incluye la posibilidad de extraer documentación de las cadenas de documentación de su código (consulte sphinx.ext.autodoc ) y reconoce las listas de campos reST siguiendo ciertas convenciones. Probablemente se haya 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 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
"""

Answer 3

El estándar para las cadenas de documentación de Python se describe en la 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 '''')
    """

Answer 4

Siga la Guía de estilo de Google Python . Tenga en cuenta que Sphinx también puede analizar este formato utilizando la extensión de 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 de Napolean vinculada anteriormente.

Un ejemplo completo de todos los tipos de documentos here .