Как комментировать параметры для pydoc

pydoc не распознает "структурированные" элементы в docstrings, он просто выводит docstring как есть. См.PEP 0257 для примера.

если вы хотите "отформатированную" документацию, вы должны использовать другой генератор документации, такой как Сфинкс, например

параметры для функций должны быть задокументированы в functions docstring. Вот пример, взятый из ответ:

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

здесь другой более явный пример, если вы хотите воспользоваться реструктурированным текстом с большим количеством дескрипторов параметров, таких как :type param: или :rtype: изъяты отсюда

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

вы также можете использовать различные форматы docstring (например, Google или включает в себя), что я рекомендую!!! чтобы сделать ваши docstrings яснее.

надеюсь, что это помогает!