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

162

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)
JF Dion
fuente
66
También hay muchas más respuestas a esto en la pregunta anterior, que es un duplicado.
Alex Dupuy

Respuestas:

227

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
"""
Steven
fuente
77
¿Qué haces si necesitas romper una línea para una descripción larga? ¿Cómo se vería eso?
Skylar Saveland
66
Consulte la referencia de reStructuredText y las listas de campos en particular: docutils.sourceforge.net/docs/ref/rst/…
Steven
66
Tenga en cuenta que la forma en que las frases aquí no cumplen con PEP 257 . Debería ser en Replace template place holder with values.lugar de replaces template place holder with values: Observe la oración, la letra mayúscula al comienzo y el punto final (.) Al final.
kratenko
1
Desde la versión 1.3, Sphinx también admite un formato un poco más agradable a través de la sphinx.ext.napoleonextensión.
Petri
3
¿Podría alguien indicarme la mejor documentación que especifique estas cadenas de documentos especiales como ": param ____:" y ": devuelve:"? Tal documento parece bastante difícil de encontrar en este momento.
krumpelstiltskin
75

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í .

confundido00
fuente
20
para todos los humanos que leen cadenas de documentos
Waylon Flinn
1
Se actualizó el enlace de la Guía de estilo de Google Python
confundido00
@ confused00 ¿cómo puedo documentar que mi método está devolviendo una matriz de objetos?
Cito
1
Ahora estoy confundido ! args o params? stackoverflow.com/questions/1788923/parameter-vs-argument
shuva
25

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 '')
    """
srgerg
fuente
17
PEP257 no dice nada sobre el formato real de la parte del argumento. Simplemente establece que debe escribirse y da un ejemplo. Pero esto es solo un ejemplo. Por lo tanto, definitivamente recomendaría usar la convención Sphinx, ya que no rompes PEP257 y usas un formato que pueda ser analizado por sphinx.
vaab
77
Excepto que la primera documentación presentada anteriormente es fea y tiene mucha información redundante para los humanos. Prefiero usar una convención que haga que mi código fuente sea agradable de leer sin ser analizado primero
confundido00
1

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.

David Cain
fuente