Adding an example to Doxygen generated Python documentation

Question

I am trying to add an example to the description of a Python class. It doesn't seem to work for some reason. The example is added to 'Example' tab on the generated HTML page just fine, but a link to the example is not shown in the description of the class. I have read the section in the doxygen manual covering the special command '@example' (http://www.doxygen.nl/manual/commands.html#cmdexample), but I still can't figure out how to do it right. It seems like no matter where I place the @example command, the link is not shown. I am using doxygen 1.8.5.

A simplified Python class where a link to an example should be shown:

class TestClass:

    ## The constructor.
    #  @param self The object pointer.
    def __init__(self):
        self.__value = 0

    ## Stores a value.
    #  @param value The value to be stored.        
    def setValue(self, value):
        self.__value = value

    ## Gets stored value.
    #  @return The stored value.                
        def getValue(self):
        return self.__value

## @example TestClass_Example.py
#  This is an example of how to use TestClass

The example looks like this:

from TestClass import TestClass

def main():
    myTestClass = TestClass()
    myTestClass.setValue(37)
    print "The stored value is:", myTestClass.getValue()    

if __name__ == '__main__':
    main()

Any help is appreciated.

Mailerdaimon Mailerdaimon · Accepted Answer · 2013-10-30T12:03:57

The Answers can be found here.

In short: You can´t use special commands (like example) using the python syntax of doxygen. You have to use comments starting with ## and then the special command.

Note that in this case none of doxygen's special commands are supported.

There is also another way to document Python code using comments that start with "##". These type of comment blocks are more in line with the way documentation blocks work for the other languages supported by doxygen and this also allows the use of special commands.

EDIT: Ahh sorry... just read that you already did this..

Are you sure that doxygen knows the Path to your file? Is it in the same directory? Try setting the EXAMPLE_PATH in the doxygen config?

Adding an example to Doxygen generated Python documentation

1 Answers