Comment blocks in Python

2017-02-04  本文已影响35人  华山论剑

For Python there is a standard way of documenting the code using so called documentation strings. Such strings are stored in doc and can be retrieved at runtime. Doxygen will extract such comments and assume they have to be represented in a preformatted way.
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
class PyClass:
"""Documentation for a class.
More details.
"""

def __init__(self):
    """The constructor."""
    self._memVar = 0;

def PyMethod(self):
    """Documentation for a method."""
    pass

Click here for the corresponding HTML documentation that is generated by doxygen.

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.

Here is the same example again but now using doxygen style comments:

@package pyexample

Documentation for this module.

More details.

Documentation for a function.

More details.

def func():
pass

Documentation for a class.

More details.

class PyClass:

## The constructor.
def __init__(self):
    self._memVar = 0;

## Documentation for a method.
#  @param self The object pointer.
def PyMethod(self):
    pass
 
## A class variable.
classVar = 0;
## @var _memVar
#  a member variable

Click here for the corresponding HTML documentation that is generated by doxygen.

Since python looks more like Java than like C or C++, you should set OPTIMIZE_OUTPUT_JAVA to YES in the config file.

上一篇 下一篇

猜你喜欢

热点阅读