python - pyplot - ¿Cómo documentar un método con parámetro(s)?

title plt python

Question

¿Cómo documentar los métodos con parámetros utilizando las cadenas de documentación de Python?

EDITAR: PEP 257 da este ejemplo:

def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...

¿Es esta la convención utilizada por la mayoría de los desarrolladores de Python?

Keyword arguments:
<parameter name> -- Definition (default value if any)

Estaba esperando algo un poco más formal, como

def complex(real=0.0, imag=0.0):
"""Form a complex number.
@param: real The real part (default 0.0)
@param: imag The imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...

Environement : Python 2.7.1

Answer 1

Como las cadenas de documentos son de forma libre, realmente depende de lo que use para analizar el código para generar documentación API.

Recomiendo familiarizarse con el marcado Sphinx , ya que es ampliamente utilizado y se está convirtiendo en el estándar de facto para la documentación de proyectos de Python, en parte debido al excelente servicio de readthedocs.org . Parafraseando un ejemplo de la documentación de Sphinx como un fragmento de Python:

def send_message(sender, recipient, message_body, priority=1):
''''''
Send a message to a recipient
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring
''''''

Este marcado admite cross-referencing entre documentos y más. Tenga en cuenta que la documentación de Sphinx utiliza (por ejemplo) :py:attr: mientras que puede usar :attr: al documentar desde el código fuente.

Naturalmente, hay otras herramientas para documentar las API. Está el Doxygen más clásico que usa commands /param pero que no están específicamente diseñados para documentar el código de Python como Sphinx.

Tenga en cuenta que hay una pregunta similar con una respuesta similar aquí ...

Answer 2

Convenciones:

• Convenciones de Docstring PEP 257
• PEP 287 ReStructuredText Formato de Docstring

Herramientas:

• Epydoc: Generación automática de documentación API para Python
• sphinx.ext.autodoc - Incluye documentación de docstrings
• PyCharm tiene un buen soporte para docstrings

Actualización: desde Python 3.5 puede usar sugerencias de tipo, que es una sintaxis compacta y legible por máquina:

from typing import Dict, Union
def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
"""
Explanation: this function takes two arguments: `i` and `d`.
`i` is annotated simply as `int`. `d` is a dictionary with `str` keys
and values that can be either `str` or `int`.
The return type is `int`.
"""

La principal ventaja de esta sintaxis es que está definida por el lenguaje y que no es ambigua, por lo que herramientas como PyCharm pueden aprovecharla fácilmente.

Answer 3

De acuerdo con mi experiencia, las convenciones numeradas de docstring (superconjunto PEP257) son las convenciones seguidas más ampliamente difundidas que también son compatibles con herramientas, como Sphinx .

Un ejemplo:

Parameters
----------
x : type
Description of parameter `x`.

Answer 4

La corriente principal es, como ya se señaló en otras respuestas, que probablemente sigan la forma de Sphinx, para que puedas usar Sphinx para generar esos documentos sofisticados más tarde.

Dicho esto, yo personalmente voy con el estilo de comentario en línea de vez en cuando.

def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()

Un ejemplo más aquí, con algunos pequeños detalles documentados en línea:

def foo( # Note that how I use the parenthesis rather than backslash "/"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass

Los beneficios (como @ mark-horvath ya se señaló en otro comentario) son:

• Lo más importante es que los parámetros y su documento permanecen siempre juntos, lo que brinda los siguientes beneficios:
• Menos tipeo (no es necesario repetir el nombre de la variable)
• Mantenimiento más sencillo al cambiar / eliminar la variable. Nunca habrá algún parámetro de documento huérfano después de cambiar el nombre de algún parámetro.
• y es más fácil encontrar el comentario que falta.

Ahora, algunos pueden pensar que este estilo se ve "feo". Pero yo diría que "feo" es una palabra subjetiva. Una forma más neutual es decir, este estilo no es convencional, por lo que puede parecer menos familiar para usted, por lo tanto, menos cómodo. De nuevo, "cómodo" es también una palabra subjetiva. Pero el punto es que todos los beneficios descritos anteriormente son objetivos. No puede lograrlos si sigue el camino estándar.

Esperemos que algún día en el futuro, habrá una herramienta de generador de documentos que también puede consumir ese estilo en línea. Eso impulsará la adopción.

PD: Esta respuesta se deriva de mi propia preferencia de usar comentarios en línea siempre que lo considere oportuno. Uso el mismo estilo en línea para documentar un diccionario también.

Answer 5

Las cadenas de docs de python son de forma libre , puedes documentarlas de la manera que quieras.

Ejemplos:

def mymethod(self, foo, bars):
"""
Does neat stuff!
Parameters:
foo - a foo of type FooType to bar with.
bars - The list of bars
"""

Ahora, hay algunas convenciones, pero Python no aplica ninguna de ellas. Algunos proyectos tienen sus propias convenciones. Algunas herramientas para trabajar con docstrings también siguen convenciones específicas.

Answer 6

Las cadenas de documentos solo son útiles en entornos interactivos, por ejemplo, el shell de Python. Al documentar objetos que no van a usarse de manera interactiva (por ejemplo, objetos internos, devoluciones de marcos), también podría usar comentarios regulares. Este es un estilo que uso para colgar comentarios sangrados de elementos, cada uno en su propia línea, para que sepa que el comentario se aplica a:

def Recomputate /
(
TheRotaryGyrator,
# the rotary gyrator to operate on
Computrons,
# the computrons to perform the recomputation with
Forthwith,
# whether to recomputate forthwith or at one''s leisure
) :
# recomputates the specified rotary gyrator with
# the desired computrons.
...
#end Recomputate

No puedes hacer este tipo de cosas con docstrings.

Answer 7

Si planea utilizar Sphinx para documentar su código, es capaz de producir documentos HTML muy formateados para sus parámetros con su función ''firmas''. http://sphinx-doc.org/domains.html#signatures