Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Documentation after members in python (with doxygen)

Tags:

python

doxygen

I am using doxygen and have the following code:

def __init__(self):
    '''

    '''
    if not '_ready' in dir(self) or not self._ready:
        self._stream = sys.stderr   ##!< stream to which all output is written
        self._ready = True          ##!< @internal Flag to check initialization of singelton

For some reason doxygen tells me that self._stream (Member _stream) is undocumented. can I document it with a comment, like the doxygen docu describes in Putting documentation after members and if so, whats the right way?

**edit:**this seems to be related to me having no new line, for example here:

class escapeMode(object):
    '''
    Enum to represent the escape mode.
    '''
    ALWAYS      = 1     ##!< Escape all values
    NECESSARY   = 2     ##!< Escape only values containing seperators or starting with quotation

Doxygen only complains about ALWAYS being undocumented, I would like to avoid inserting newlines behind every new attribute I document this way since it destroys the value of newlines for separating logical blocks like loops or if statements from surrounding code

like image 795
ted Avatar asked Jun 15 '12 16:06

ted


People also ask

Does doxygen work for Python?

Doxygen: It is not the tool of choice for most Python projects. But if you have to deal with other related projects written in C or C++ it could make sense. For this you can improve the integration between Doxygen and Python using doxypypy. Sphinx: The defacto tool for documenting a Python project.

How do you do documentation in python?

As you learned that docstrings are accessible through the built-in Python __doc__ attribute and the help() function. You could also make use of the built-in module known as Pydoc , which is very different in terms of the features & functionalities it possesses when compared to the doc attribute and the help function.

What is doxygen style comments?

A special comment block is a C or C++ style comment block with some additional markings, so doxygen knows it is a piece of structured text that needs to end up in the generated documentation. The next section presents the various styles supported by doxygen.

How to document Python code in doxypy?

Doxypy appears to be dead and gone.. This is documented on the doxygen website, but to summarize here: You can use doxygen to document your Python code. You can either use the Python documentation string syntax: """@package docstring Documentation for this module. More details. """ def func (): """Documentation for a function.

How to create a Doxygen example program in Python?

It contains various types of elements (e.g. constants, variables, functions, classes, modules, etc.) that are common in Python programs. Create a project directory named MyDoxygenExample and go into that directory. Create a src directory under the project directory and go into that directory as well. This is where we will place our source code.

What is a Doxygen comment in Python?

They merely provide an example of how to comment your source code so that it can be properly parsed by the Doxygen utility. It contains various types of elements (e.g. constants, variables, functions, classes, modules, etc.) that are common in Python programs.

How do I parse the source code in Doxygen?

In order to effectively parse the source code to generate our project documentation, Doxygen requires the use of a configuration file. This file, named Doxyfile by default, is where we set up our project specific information and tell Doxygen how to parse the Python code.


1 Answers

This is currently not supported in doxygen, as previously answered here. If you put the comment on the preceeding line it will work fine:

class escapeMode(object):
    '''
    Enum to represent the escape mode.
    '''
    ## Escape all values
    ALLWAYS     = 1
    ## Escape only values containing seperators or starting with quotation
    NECESSARY   = 2

Hope that's not too late...

like image 77
Duncan Macleod Avatar answered Nov 06 '22 06:11

Duncan Macleod