Doxygen links for a multi-language API

Viewed 26

We use Doxygen to generate the API and related documentation for our software library. The library is written in C++, exposes a C interface, and includes wrappers for other languages like C# and Python.

Much of the wrapper languages use the same names for structures/classes as the C API. When Doxygen finds one of them it always links to the C structure. I believe I read somewhere this is by design--it links to the first one that was found. How can I get Doxygen to link the one for a particular language? Ideally to also have the generated link only show the structure/class name (ie. not have some prefix).

Very basic example with pseudo-code in case it helps:

C++ pseudo-code:

ConfigurationOptions.h:

/// Data container
struct ConfigurationOptions
{
}

Bar.h:

/// Class to manage ... 
class Bar
{
    /// Construct object based on specified options.
    ///
    /// \param options
    ///    A ConfigurationOptions object with ...
    Bar(const ConfigurationOptions & options);
}

Python pseudo-code:

ConfigurationOptions.py:

## Data container
class ConfigurationOptions(structure):
    def __init__(self):
        self.count = 10

Bar.py:

## Class to manage ...
class Bar:
    ## Construct object based on specified options.
    ## See ConfigurationOptions documentation.
    ##
    ## \param options [ConfigurationOptions]
    ##   A ConfigurationOptions object with ...
    def __init__(self, options):

When both files are included in the Doxygen configuration, it will auto-link all references to ConfigurationOptions to the C++ struct ConfigurationOptions. I want the Python documentation to link to the Python objects.

To be clear, using this example, I want the references to ConfigurationOptions in Bar.py (lines 4, 6, 7) to link to the Python ConfigurationOptions, not the C++ one.

I've found a way to do it (at least with Python) by prefixing the element with the name of the Python module (file). For example:

    ## \param options [ConfigurationOptions.ConfigurationOptions]
    ##   A ConfigurationOptions.ConfigurationOptions object with ...

But there's downsides to this, and I don't know if it'll work with the other languages.

1 Answers

The problem looks related to the version used, when I use the 1.8.17 version and the current version (1.9.5) I get as class list:

enter image description here

Though when I use the current master version (Doxyfile 1.9.6 (28ec5dc5a74e0b2cbf66ea0fde2696f9c5c340be)) I get:

enter image description here

So it looks to me that there is in the current master a better separation between the python and the C++ part (the python part show though the artificial namespace). It has to be checked whether or not the links are al correct.

Edit

Regarding the extra problem of the links from python that should link to python I see the following possibilities:

  • use full qualified names so for ConfigurationOptionsuse ConfigurationOptions.ConfigurationOptions
  • see to it that the C++ code is embedded into a namespace (maybe conditional just for the documentation (see the doxygen commands like \cond or use preprocessor commands for it).
Related