How to document python function parameter types?

Question

I know that the parameters can be any object but for the documentation it is quite important to specify what you would expect.

First is how to specify a parameter ty

Answer 1

There is a better way. We use

def my_method(x, y):
    """
    my_method description

    @type x: int
    @param x: An integer

    @type y: int|string
    @param y: An integer or string

    @rtype: string
    @return: Returns a sentence with your variables in it
    """

    return "Hello World! %s, %s" % (x,y)

That's it. In the PyCharm IDE this helps a lot. It works like a charm ;-)

Answer 2

You need to add an exclamation mark at the start of the Python docstring for Doxygen to parse it correctly.

def myMethod(self, name, image):
    """!
    Does something ...

    @param name String: name of the image
    @param image Image: instance of Image Class or a string indicating the filename.

    @return Return True if operation succeeded or False.
    """
    return True

Answer 3

Figured I'd post this little tidbit here since IDEA showed me this was possible, and I was never told nor read about this.

>>> def test( arg: bool = False ) -> None: print( arg )

>>> test(10)
10

When you type test(, IDLE's doc-tip appears with (arg: bool=False) -> None Which was something I thought only Visual Studio did.

It's not exactly doxygen material, but it's good for documenting parameter-types for those using your code.

Answer 4

Yup, @docu is right - this is the (IMHO best) way to combine both documentation schemes more or less seamlessly. If, on the other hand, you also want to do something like putting text on the doxygen-generated index page, you would add

##
# @mainpage (Sub)Heading for the doxygen-generated index page
# Text that goes right onto the doxygen-generated index page

somewhere at the beginning of your Python code.

In other words, where doxygen does not expect Python comments, use ## to alert it that there are tags for it. Where it expects Python comments (e.g. at the beginning of functions or classes), use """!.

Answer 5

If using Python 3, you can use the function annotations described in PEP 3107.

def compile(
   source: "something compilable",
   filename: "where the compilable thing comes from",
   mode: "is this a single statement or a suite?"):

See also function definitions.

Answer 6

Doxygen is great for C++, but if you are working with mostly python code you should give sphinx a try. If you choose sphinx then all you need to do is follow pep8.