23

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 types like these below?

  • str (or use String or string?)
  • int
  • list
  • dict
  • function()
  • tuple
  • object instance of class MyClass

Second, how to specify params that can be of multiple types like a function that can handle a single parameter than can be int or str?

Please use the below example to demonstrate the syntax needed for documenting this with your proposed solution. Mind that it is desired to be able to hyperlink reference to the "Image" class from inside the documentation. 

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

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

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

Note, you are welcome to suggest the usage of any documentation tool (sphinx, oxygen, ...) as long it is able to deal with the requirements.

Update:

It seams that there is some kind of support for documenting parameter types in doxygen in. general. The code below works but adds an annoying $ to the param name (because it was initially made for php).

    @param str $arg description
    @param str|int $arg description
sorin
  • 161,544
  • 178
  • 535
  • 806
  • 2
    The best documentation you can provide for inputs and outputs is a suite of passing unit tests, using the [`unittest` framework](http://www.python.org/doc//current/library/unittest.html). – johnsyweb Oct 10 '11 at 11:30
  • @Johnsyweb your link is sadly broken https://docs.python.org/2/library/unittest.html – Kev1n91 Mar 04 '18 at 11:46
  • 7+ years later https://docs.python.org/2/library/unittest.html or https://docs.python.org/3/library/unittest.html should work. – johnsyweb Mar 05 '18 at 01:14

6 Answers6

16

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

Tony Melony
  • 161
  • 1
  • 3
  • 1
    This doesn't appear to work. When I added an '!' after the opening quotes, it worked. – SW_user2953243 Sep 13 '14 at 17:21
  • 2
    1) To create function documentation press alt+Enter in function header and select "insert documentation string stub" https://www.jetbrains.com/pycharm/webhelp/creating-documentation-comments.html 2) The default format of docstrings in PyCharm is "restructured text". You can change it to Epytext (as in above Tony Melony listing) at File->Settings->Python Integrate Tools->Dostring Format . See epydoc reference http://epydoc.sourceforge.net/epytext.html – d9k Nov 08 '14 at 03:41
  • pydev in eclipse likes this too – shrewmouse Dec 02 '22 at 15:59
6

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
docu
  • 61
  • 1
  • 1
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.

robert
  • 33,242
  • 8
  • 53
  • 74
  • 1
    But are there aren't any documentation processors that support this yet, are there? Seems like [sphinx doesn't](http://stackoverflow.com/questions/2194777/in-sphinx-is-there-a-way-to-document-parameters-along-with-declaring-them), and I can't find anything about doxygen support either. – naught101 Sep 02 '14 at 00:27
  • 1
    Three years ago I thought it would have been by now. – robert Sep 21 '14 at 18:05
1

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.

Tcll
  • 7,140
  • 1
  • 20
  • 23
0

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

user147058
  • 1
  • 2
0

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.

ggorlen
  • 44,755
  • 7
  • 76
  • 106
Tom
  • 1,986
  • 2
  • 18
  • 29
  • 1
    The main reason is because the project already uses doxygen and second, sphinx is not able to document parameter types. – sorin Oct 10 '11 at 11:22
  • And sphinx does not document code automatic. It does not recognize new functions etc by default. You have to explicit add them. All sphinx addons taking this into account do not work probably. – buhtz Aug 29 '21 at 10:49