Add command for "documentation fallback" for a class or namespace

[eyalroz]

Describe the bug
When one:

• Defines specializations of a template, which share several methods, or
• Defines several classes which share multiple methods, or
• Defines two namespaces with corresponding functions,

one often wants to use the documentation from one class/namespace in the other for some cases, and for other cases to pen some different documentation. At the moment, this must be done by @copydoc'ing every member (of the class or the namespace), pointing at the corresponding member of the other namespace or class.

Expected behavior
I propose that doxygen offer a "documentation fallback" command, usable at class or namespace scope (actually, perhaps also file scope) - and referring to another class or namespace (or file), respectively. Example syntax might be \\\docfallback bar.

Now, when no documentation at all is not provided for a member of that scope with signature foo - doxygen will consider it to have had a '\\\@copydoc bar::foo command.

Example

sources.zip

Classes:

class A {
public:
    /// Does foo
    A& foo();

    /// Does bar
    A& bar(int x);

    /// Does quux
    A& quux(int x, int z);
};

class B {
public:
    B& baz(double y);
    B& bar(int x);
    B& quux(int x, int z);
};

I want the functions in B, which have an exact counterpart in A (bar and quux) to use the documentation of the A methods - without having to @copydoc twice

Namespaces:

namespace ugly {
/**
 * @brief Perform a manipulation on a number.
 * @param x the number to be manipulated
 */
int manipulate(int x);

/**
 * @brief Perform a transmogrification a number.
 * @param x the number to be transmogrified
 */
int transmogrify(int x);
} // namespace ugly

namespace beautiful {
int manipulate(int x);
int transmogrify(int x);
} // namespace ugly

I want the functions in the beautiful namespace to use the same documentation as their counterparts in the ugly namespace.

[albert-github]

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).
• Please also specify the full doxygen version used (doxygen -v).

[eyalroz]

@albert-github : I can't, because this is not a problem, it's a feature request. But I will attach a couple of source files in which this feature could be used. See edit of first post.

[albert-github]

I can't, because this is not a problem, it's a feature request. But I will attach a couple of source files in which this feature could be used. See edit of first post.

Well you managed to add a nice example to the original post that can be used as a starting point to see what is necessary / wanted.

I looked at the classes example and here I see that the functions bar and quux don't have the same signature as they return a different type of argument (A& and B&). Can't this problem be implemented with templates and sub / super classes?

[eyalroz]

I looked at the classes example and here I see that the functions bar and quux don't have the same signature as they return a different type of argument (A& and B&). Can't this problem be implemented with templates and sub / super classes?

With templates - yes and no, because if A becomes MyClass<0> and B becomes MyClass<1>, specialized differently - the respective methods would still need to return MyClass<0>& and MyClass<1>& respectively; and those are two different return types. Even if one managed to phrase them the same way, e.g. via static constexpr const the_template_argument which gets 0 or respectively 1, and a method returning MyClass<the_teplate_argument> - it's still a different class.

As for using superclasses - that won't help, because then you can't use methods of the subclass, i.e. I want to write something like make_an_A().bar(123).foo() (builder pattern).

I was assuming that name + parameters should be enough for referencing in doxygen (i.e. @ref, @copydoc, @copyparam, etc. etc.)