Documenting a non-existing member with Doxygen

Question

I'm trying to document a python class using Doxygen. The class exposes a set of properties over d-bus, but these have no corresponding public getters/setters in the python class. Instead, they are implemented through a d-bus properties interface (Set/Get/GetAll/Introspect).

What I want to do is to be able to document these properties using something like this:

## @property package::Class::Name description

The whole package::Class works (the same method finds functions, so it finds the right class).

When running doxygen I get the following error:

warning: documented function ``package::Class::Name' was not declared or defined.

I can live with a warning, but unfortunately the property fails to appear in the documentation generated for the class, so it is not only a warning, but it is silenced as well.

So, my question is, how, if I can, do I make the non-existing property member appear in the generated docs?

score 3 · Accepted Answer · edited Jan 31 '13 at 22:14

Define the attribute inside an if 0: block:

## @class X
## @brief this is useless
class X:
    if 0:
        ## @brief whatevs is a property that doesn't exist in spacetime
        ##
        ## It is designed to make bunny cry.
        whatevs = property

This will cause it to exist in the documentation (tested with doxygen 1.8.1.2-1 on debian-squeeze). The attribute will never be made to exist at runtime, and in fact it looks like the python bytecode optimizer eliminates if statement and its body altogether.

score 0 · Answer 2 · edited Mar 24 '19 at 17:54

I looked into something similar previously and couldn't find a direct way to coax Doxygen into documenting an undefined member. There are two basic kludges you can use here:

1.) generate a dummy object (or dummy members) for doxygen to inventory which don't actually exist in the live code.

2.) If the adjustments you need are fairly predictable and regular you could write an INPUT_FILTER for doxygen which takes your files and converts them before parsing. There are some issues with this method--mostly that if you plan on including the code in the documentation and the filter has to add/remove lines from the file, the line numbers it indicates will be off, and any code windows shown with the documentation will be off by that number of lines. You can also check the option to filter the displayed sources to adjust for this, but depending on who the consumer of your documentation is, it may be confusing for the copy in Doxygen not to perfectly match what's in the real source.

In our case we use a python script which Doxygen runs from the command-line with the file path as the arg. We read the file indicated and write what we want Doxygen to interpret instead to stdout. If you need the source copies displayed in doxygen to be filtered as well you can set FILTER_SOURCE_FILES to YES.

Documenting a non-existing member with Doxygen

2 Answers2

Linked