0

I have the following problem: I want to add code examples to my doxygen documentation. It works fine, but I have quite some examples, each of which needs to call the same function, say, myInit(). Now, the generated documentation for myInit() contains all examples that use myInit(), which basically means: all examples. I would like to have exactly one example referred to for myInit(), namely that one which demonstrates the usage of it, but not all of them.

Here is an example:

=============== MyEspressoMachine.h ==============
/** @example exTurnOn.cpp */
/** @example exMakeEspresso.cpp */
/** @example exClean.cpp */
/** @example exTurnOff.cpp */

/** My espresso machine. */
class MyEspressoMachine {
public:
    /** Turns the espresso machine on */
    void turnOn() {};
    /** Makes a delicious espresso.  */
    void makeEspresso() {};
    /** Cleans the espresso machine.  */
    void clean() {};
    /** Turns the espresso machine off */
    void turnOff() {};
};
=============== exTurnOn.cpp =============
#include "MyEspressoMachine.h"
int main() {
    MyEspressoMachine m;
    m.turnOn();
    m.turnOff();
}
=============== exMakeEspresso.cpp ==============
#include "MyEspressoMachine.h"
int main() {
    MyEspressoMachine m;
    m.turnOn();
    m.makeEspresso();
    m.turnOff();
}
=============== exClean.cpp ==============
#include "MyEspressoMachine.h"
int main() {
    MyEspressoMachine m;
    m.turnOn();
    m.clean();
    m.turnOff();
}
=============== exTurnOff.cpp ==============
#include "MyEspressoMachine.h"
int main() {
    MyEspressoMachine m;
    m.turnOn();
    m.turnOff();
}
=============== Doxyfile ==============
EXAMPLE_PATH = .

Here is the result (Doxygen 1.8.7):

enter image description here

In my real case, it's not only four examples, but dozens. Though, in the documentation for turnOn, I only want exTurnOn.cpp to appear.

Any ideas?

bye, loki

oguz ismail
  • 1
  • 16
  • 47
  • 69
loki
  • 21
  • 2
  • Which version of doxygen are you using? Please show an example of what you want to accomplish. here might be a very small possibility to accomplish this (by means of `
    ` or the `%` sign), but to be able to say more we need an example.
     – albert Apr 13 '22 at 15:41
  • @albert: I added a simple example to my original post. Actually, I found that I'm not the first one with this problem: https://stackoverflow.com/questions/42865486/doxygen-selectively-remove-links-for-example-programs But his question has not been answered. So is there no solution? I'd be surprised if this is such an exotic problem... – loki Apr 14 '22 at 05:23
  • Doxygen 1.8.7 is very old (April, 21 2014) so I would certainly advise to update to the current version (1.9.3). The update won't solve your problem though. – albert Apr 14 '22 at 07:24

1 Answers1

0

Not an answer to solve the problem, but more a workaround.

The output in doxygen is a bit strange to me too, but maybe there is a reason for this. It looks like that the examples mentioned at the beginning of the file are not only mentioned on the class level but also (partly) in the class methods.

Al a first workaround I would suggest:

/** \file */

/** My espresso machine. */
class MyEspressoMachine {
public:
    /** Turns the espresso machine on
     *
     * @myExample exTurnOn.cpp
     */
    void turnOn() {}
    /** Makes a delicious espresso.
     *
     * @myExample exMakeEspresso.cpp
     */
    void makeEspresso() {}
    /** Cleans the espresso machine.
     *
     * @myExample exClean.cpp
     */
    void clean() {}
    /** Turns the espresso machine off
     *
     * @myExample exTurnOff.cpp
     */
    void turnOff() {}
};

and setting in the Doxyfile:

ALIASES = myExample="**Example:** ^^ @include"

or for the 1.8.7 version:

ALIASES = myExample="**Example:** \n @include"
albert
  • 8,285
  • 3
  • 19
  • 32
  • Thank you for the answer. I already tried to include the examples, but this makes the whole page somewhat confusing. Would it be possible to deactivate the automatic link generation for the examples, an explicitly add links only where I want them to be? – loki Apr 19 '22 at 11:11