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

9 minutos de lectura

avatar de usuario
David Andreoletti

¿Cómo documentar métodos con parámetros usando 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)

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

Ambiente: Pitón 2.7.1

  • ¿Has leído PEP 257? python.org/dev/peps/pep-0257

    – ENP

    8 de febrero de 2012 a las 14:47

  • Existen varios ‘estándares’, pero en un enfoque práctico y especialmente si te gusta algo formal, recomendaría esfinge. Su integración en Pycharm hace que la generación de cadenas de documentos bien estructuradas sea bastante sencilla. En mi humilde opinión

    – jojo

    24 de junio de 2014 a las 9:24


avatar de usuario
anarquista

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

Recomendaría familiarizarse con el marcado de esfingeya que se usa ampliamente y se está convirtiendo en el estándar de facto para documentar proyectos de Python, en parte debido a la excelente readthedocs.org Servicio. A parafrasear 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 solo puedes usar :attr: al documentar desde el código fuente.

Naturalmente, existen otras herramientas para documentar las API. Está el más clásico. doxígeno que utiliza \param comandos pero esos no están diseñados específicamente para documentar el código de Python como lo es Sphinx.

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

  • Este es el estilo utilizado por la autogeneración de comentarios de PyCharm por defecto

    – Josías Yoder

    1 de septiembre de 2017 a las 16:31

  • ¿Qué pasa con la sintaxis de tipos compuestos como listas de cosas?

    – matanster

    28 de junio de 2018 a las 14:23


  • entonces es un list.

    – anarcato

    1 de julio de 2018 a las 14:49

  • No sé por qué no recomiendan poner una línea vacía entre cada par de tipo de parámetro. Esto es tan feo.

    – Ereghard

    22 de junio a las 8:47

  • @Ereghard ser compacto siempre es mejor, te acostumbrarás con el tiempo.

    – alper

    22 de junio a las 9:46

avatar de usuario
vladimir keleshev

Basado en mi experiencia, el convenciones numpy docstring (PEP257 superset) son los más difundidos seguido convenciones que también son compatibles con herramientas, como Esfinge.

Un ejemplo:

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

  • Esto se acerca más a lo que esperaba. Desafortunadamente, elegí PEP 257 simple y agregué mi propia convención (a costa de perder la documentación HTML/PDF generada automáticamente). Sin embargo, la próxima vez, elegiré esta solución. Gracias.

    –David Andreoletti

    11 de abril de 2012 a las 5:51

  • Cuando intento procesar la cadena de documentación sugerida, Sphinx se queja SEVERE: Unexpected section title — ¿Conoces alguna forma de hacer que Sphinx esté más feliz al respecto?

    – Brandon Rodas

    21 de enero de 2014 a las 4:54

  • @BrandonRhodes este enlace habla sobre el uso de estas convenciones con Sphinx: github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

    – Vladímir Keleshev

    7 mayo 2015 a las 9:00

  • En realidad falta un espacio antes Description. Revisé la documentación numpy, porque inmediatamente me di cuenta y pensé “Espera un segundo, ¿por qué es Tres espacios? Eso es extraño. ¿Quién usaría tres espacios?”

    –Zelphir Kaltstahl

    18/04/2016 a las 18:36

  • Esta puede haber sido la mejor respuesta en el momento en que se hizo la pregunta, pero creo que a partir de ahora (finales de 2017), Sphinx ha salido victoriosa.

    – Alex L.

    31 de octubre de 2017 a las 0:02

avatar de usuario
Jakub Roztócil

Convenciones:

Instrumentos:


Actualización: desde Python 3.5 puedes usar escriba sugerencias que es una sintaxis compacta, 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.

  • Aunque esta respuesta es ahora la más votada, ninguno de los PEP anteriores proporciona una convención para especificar los tipos de argumentos de un método.

    – cilantro

    23 de septiembre de 2013 a las 7:32

Las cadenas de documentos de Python son forma librepuede documentarlo de la forma que desee.

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 cadenas de documentos también siguen convenciones específicas.

Si planea usar Sphinx para documentar su código, es capaz de producir documentos HTML bien formateados para sus parámetros con su característica de ‘firmas’. http://esfinge-doc.org/dominios.html#firmas

La corriente principal es, como ya señalaron otras respuestas aquí, probablemente yendo con el camino de la esfinge para que pueda usar Sphinx para generar esos documentos elegantes más tarde.

Dicho esto, personalmente uso 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ñaló en otro comentario) son:

  • Lo que es más importante, los parámetros y su documentación siempre permanecen juntos, lo que brinda los siguientes beneficios:
  • Menos tipeo (no es necesario repetir el nombre de la variable)
  • Mantenimiento más fácil al cambiar/eliminar variable. Nunca habrá algún párrafo de documento de parámetro huérfano después de cambiar el nombre de algún parámetro.
  • y más fácil de 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 neutral es decir que este estilo no es convencional, por lo que puede parecerle menos familiar y, por lo tanto, menos cómodo. Una vez más, “cómodo” también es una palabra subjetiva. Pero el punto es que todos los beneficios descritos anteriormente son objetivos. No puedes lograrlos si sigues el camino estándar.

Con suerte, algún día en el futuro, habrá una herramienta generadora de documentos que también pueda 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 cuando lo crea conveniente. También uso el mismo estilo en línea para documentar un diccionario.

avatar de usuario
DreamFlasher

Sobre la base de la respuesta de sugerencias de tipo (https://stackoverflow.com/a/9195565/2418922), que proporciona una forma mejor estructurada de documentar los tipos de parámetros, también existe una forma estructurada de documentar tanto el tipo como las descripciones de los parámetros:

def copy_net(
    infile: (str, 'The name of the file to send'),
    host: (str, 'The host to send the file to'),
    port: (int, 'The port to connect to')):

    pass

ejemplo adoptado de: https://pypi.org/project/autocommand/

  • ¿Es esta una sintaxis oficial? Es muy útil, sin embargo, no puedo encontrarlo en los documentos oficiales/PEP…

    – Ofri Raviv

    8 de marzo de 2020 a las 15:32

  • Me gustaría saber eso también, si hay un PEP para eso.

    – DreamFlasher

    9 de marzo de 2020 a las 12:38

  • Esto parece que significaría “una tupla de dos elementos: una cadena y una cadena literal, una escritura. Literal, con el texto “El nombre del archivo para enviar”‘; así es como Pyright lo interpreta. Aunque posiblemente bien, a menos que se adopte explícitamente un PEP para permitir esto en el futuro, no creo que esta sea la respuesta correcta.

    – Ivan Vučica

    31 de agosto de 2021 a las 22:42

¿Ha sido útil esta solución?

Esta web utiliza cookies propias y de terceros para su correcto funcionamiento y para fines analíticos y para mostrarte publicidad relacionada con sus preferencias en base a un perfil elaborado a partir de tus hábitos de navegación. Al hacer clic en el botón Aceptar, acepta el uso de estas tecnologías y el procesamiento de tus datos para estos propósitos. Configurar y más información
Privacidad