Cómo comentar los parámetros para pydoc

Es allí una manera de comentar los parámetros de una función para hacer que sean reconocidos por los pydoc de la biblioteca ?

yo.e ¿cuál es el docstring para pydoc?

Posibles duplicados de Cómo documentar un método con un parámetro(s)?
Steven Vascellaro. Por el contrario, con la posible duplicar, esta pregunta es específica para el pydoc de la biblioteca.

OriginalEl autor PatriceG | 2015-12-17

2 respuestas

  1. 23

    pydoc no reconocer “estructurada” elementos en docstrings, apenas salidas de la docstring como es. Ver PEP-257 para un ejemplo.

    Si quieres un “formato” de la documentación se debe usar otro generador de documentación, tales como Esfinge o pdoc, por ejemplo.

    Los parámetros para las funciones tienen que ser documentados en las funciones docstring. He aquí un ejemplo tomado de la esta respuesta:

    """
    This example module shows various types of documentation available for use
    with pydoc.  To generate HTML documentation for this module issue the
    command:
    
        pydoc -w foo
    
    """
    
    class Foo(object):
        """
        Foo encapsulates a name and an age.
        """
        def __init__(self, name, age):
            """
            Construct a new 'Foo' object.
    
            :param name: The name of foo
            :param age: The ageof foo
            :return: returns nothing
            """
            self.name = name
            self.age
    
    def bar(baz):
        """
        Prints baz to the display.
        """
        print baz
    
    if __name__ == '__main__':
        f = Foo('John Doe', 42)
        bar("hello world")

    Aquí es otra más explícita ejemplo, si usted desea tomar ventaja de reestructurada de texto con un número mayor de parámetros descriptores, como :type param: o :rtype: tomado desde aquí

    """
    The ``obvious`` module
    ======================
    
    Use it to import very obvious functions.
    
    :Example:
    
    >>> from obvious import add
    >>> add(1, 1)
    2
    
    This is a subtitle
    -------------------
    
    You can say so many things here ! You can say so many things here !
    You can say so many things here ! You can say so many things here !
    You can say so many things here ! You can say so many things here !
    You can say so many things here ! You can say so many things here !
    
    This is another subtitle
    ------------------------
    
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
    consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
    proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    
    """
    
    def add(a, b):
        """
        Adds two numbers and returns the result.
    
        This add two real numbers and return a real result. You will want to
        use this function in any place you would usually use the ``+`` operator
        but requires a functional equivalent.
    
        :param a: The first number to add
        :param b: The second number to add
        :type a: int
        :type b: int
        :return: The result of the addition
        :rtype: int
    
        :Example:
    
        >>> add(1, 1)
        2
        >>> add(2.1, 3.4)  # all int compatible types work
        5.5
    
        .. seealso:: sub(), div(), mul()
        .. warnings:: This is a completly useless function. Use it only in a 
                  tutorial unless you want to look like a fool.
        .. note:: You may want to use a lambda function instead of this.
        .. todo:: Delete this function. Then masturbate with olive oil.
        """
        return a + b

    También puede utilizar diferentes docstring formatos (como Google o Numpy), que me recomiendan!!! para hacer su docstrings más clara.

    Espero que esto ayude!

    Gracias. Ya he probado la primera docstring. Sin embargo, la :param no es “reconocido” por pydoc y aparecen como los otros comentarios en el documento html generado.
    Pydoc no reconocer “estructurada” elementos en docstrings, apenas salidas de la docstring como es. Consulte PEP 0257 para ver un ejemplo. Si desea que este tipo de característica, usted tendrá que otro usuario generador de documentación como respondí anteriormente. Lo siento por la confusión, voy a editar mi respuesta
    Ok, así que finalmente la respuesta es “no trabajar con pydoc, yo podría usar Sphinx si yo quiero hacer eso”. A la derecha ?
    Sí, pydoc fue diseñado simplemente para que la salida de la documentación en un entorno de terminal. La esfinge es bastante fácil de configurar.
    el aceite de oliva trabajado maravillas!!!

    OriginalEl autor Ire

  2. 2

    Otro ejemplo

    #!/usr/bin/env python
    
    """
    Module documentation
    A small example of comments usage
    """
    
    # regular comment,
    # will not visible by pydoc
    spam = 40
    
    
    def square(x):
        """
        this function will return square(x) value
        :param x: any number
        :return: example doc for return
        """
        return x ** 2
    
    import abc
    
    
    class ListInherited:
        """
            Class ListInherited doc example
            This class use dir() function for list instance attributes
        """
    
        def __init__(self, arg1):
            """
            my constructor
            :param arg1: example value
            :return:
            """
            self.arg1 = arg1
    
        def __str__(self):
            """
            to string conversion
            :return:
            """
            tup = (self.__class__.__name__, id(self), self.attr_names())
            return '<Instance of %s, address %s:\n%s>' % tup
    
        def attr_names(self):
            """
            get attribute names
            :return: string
            """
            result = ''
    
            for attr in dir(self):
                if attr[:2] == '__' and attr[-2:] == '__':  # skip "build-in"
                    result += '\t name %s=<>\n' % attr
                else:
                    result += '\t name %s=%s\n' % (attr, getattr(self, attr))
            return result
    
        @staticmethod
        def my_static_method(count):
            """
            static method comment example
            :param count:
            :return:
            """
            return "Hello, I'm static" * count
    
    
    if __name__ == "__main__":
        import test3
    
        x = 33
        y = test3.square(x)
    
        print(test3.__doc__)
        print(test3.square.__doc__)
    
        instance = ListInherited(1)
        print(instance.__doc__)

    En la consola de python

    >>> import test3
    >>> help(test3)

    De salida:

    Help on module test3:
    
    NAME
        test3
    
    FILE
        /home/mrdinkelman/PycharmProjects/testproject27/test3.py
    
    DESCRIPTION
        Module documentation
        A small example of comments usage
    
    CLASSES
        ListInherited
    
        class ListInherited
         |  Class ListInherited doc example
         |  This class use dir() function for list instance attributes
         |  
         |  Methods defined here:
         |  
         |  __init__(self, arg1)
         |      my constructor
         |      :param arg1: example value
         |      :return:
         |  
         |  __str__(self)
         |      to string conversion
         |      :return:
         |  
         |  attr_names(self)
         |      get attribute names
         |      :return: string
         |  
         |  ----------------------------------------------------------------------
         |  Static methods defined here:
         |  
         |  my_static_method(count)
         |      static method comment example
         |      :param count:
         |      :return:
    
    FUNCTIONS
        square(x)
            this function will return square(x) value
            :param x: any number
            :return: example doc for return
    
    DATA
        spam = 40
    Gracias. Sin embargo, es el “:param” palabra clave reconocido por la ayuda()? Parece que la impresión es como cualquier otro comentario.

    OriginalEl autor mrDinkelman

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *