¿Cómo documentar un método con parámetros?
¿Cómo documentar métodos con parámetros usando las cadenas de documentación de Python?
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)
Esperaba 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
...
Entorno: Python 2.7.1
Dado que las cadenas de documentación tienen un formato libre, realmente depende de lo que uses para analizar el código para generar documentación API.
Recomendaría familiarizarse con el marcado Sphinx , ya que se usa ampliamente y se está convirtiendo en el estándar de facto para documentar proyectos de Python, en parte debido al excelente servicio 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) -> int:
"""
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 referencias cruzadas entre documentos y más. Tenga en cuenta que la documentación de Sphinx usa (por ejemplo), :py:attr:mientras que usted puede usarlo :attr:cuando documenta desde el código fuente.
Naturalmente, existen otras herramientas para documentar las API. Existe el Doxygen más clásico que usa \param comandos , pero no están diseñados específicamente para documentar el código Python como lo está Sphinx.
Tenga en cuenta que hay una pregunta similar con una respuesta similar aquí...
Según mi experiencia, las convenciones de cadenas de documentación numerosas (superconjunto PEP257) son las convenciones seguidas más ampliamente y que también son compatibles con herramientas como Sphinx .
Un ejemplo:
Parameters
----------
x : type
Description of parameter `x`.
Convenciones:
- PEP 257 Convenciones de cadena de documentos
- Formato de cadena de documentación de texto reestructurado PEP 287
Herramientas:
- Epydoc: Generación automática de documentación API para Python
- sphinx.ext.autodoc: incluye documentación de cadenas de documentos
- PyCharm tiene un buen soporte para cadenas de documentos
Actualización: desde Python 3.5 puedes 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 no es ambigua, por lo que herramientas como PyCharm pueden aprovecharla fácilmente.
