Wie Parameter für pydoc kommentieren

Question

Gibt es eine Möglichkeit, die Parameter einer Funktion zu kommentieren, damit sie von der Pydoc-Bibliothek erkannt werden?

ie was ist der Docstring für pydoc?

Answer 1

pydoc erkennt "strukturierte" Elemente in Docstrings nicht, es gibt nur den Docstring aus, so wie er ist. Ein Beispiel finden Sie in PEP 0257.

Wenn Sie eine „formatiert“ Dokumentation möchten Sie eine andere Dokumentation Generator verwenden sollten, wie Sphinx zum Beispiel

Die Parameter für Funktionen in den Funktionen docstring zu dokumentieren. Hier ist ein Beispiel aus this answer genommen:

""" 
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") 

Hier ist ein weiteres deutliches Beispiel, wenn Sie die Vorteile des neu strukturiert Textes mit mehr Parametern Deskriptoren nehmen wollen, wie :type param: oder :rtype: genommen from here

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

Sie kann auch verschiedene Docstring-Formate verwenden (wie Google oder Numpy), die ich empfehle !!!, um Ihre Docstrings klarer zu machen.

Hoffe, das hilft!

Answer 2

Ein weiteres Beispiel

#!/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__) 

In Python Konsole

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

Ausgang:

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