A function cannot be documented as related to two classes. (Origin: bugzilla #124252)

[doxygen]

status NEW severity normal in component general for ---
Reported in version 1.3.x on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

• doxygen-bug.tar.gz (ID 20614)

On 2003-10-09 22:48:09 +0000, bjackson@ah.ddiglobal.com wrote:

The \relates and \relates also commands cannot be used to document a global
function as related to two or more classes.

On 2003-10-09 22:48:59 +0000, bjackson@ah.ddiglobal.com wrote:

Created attachment 20614
Examples in compressed tar file.

On 2003-10-09 22:52:48 +0000, bjackson@ah.ddiglobal.com wrote:

Please see the classes in the file B.h in the attached doxygen-bug.tar.gz.

On 2018-06-16 12:49:59 +0000, albert wrote:

*** Bug 612617 has been marked as a duplicate of this bug. ***

On 2018-06-16 17:12:55 +0000, albert wrote:

We have here multiple problems:
- silently ignoring the fact that multiple use in one comment block of
\relates or \relatesalso or \memberof or a mixture is silently ignored (only
last command is active). For this I've just pushed a proposed patch to
github (pull request 767, https://github.com/doxygen/doxygen/pull/767).
- only one \relatesalso or \relates is possible. This problem remains and is
a bit more complex. For \relates it not really solvable as links cannot go
to a fixed point. For \relatesalso the fixed point can be "it at its normal
file documentation location." This would require some sort of array or
stack. It should also be seen as an error when \relates, \relates or
\memberof are mixed.

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.8.15.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).

[Hyperlynx2]

In 1.8.15 this is only fixed in one particular case, and does not work at all for macros:

classA.hpp:

class classA
{
public:
    void oneFunction();
}

classB.hpp:

class classB
{
public:
    void anotherFunction();
}

related.hpp

//! @relates classA classB
void related();

//! @relates classA
//! @relates classB
void related2();

//! @relatedalso classA classB
void relatedAlso();

//! @relatedalso classA
//! @relatedalso classB
void relatedAlso2();

//! @relates classA
//! @relatedalso classB
void relatedRelatedAlso();

//! @relatedalso classA
//! @related classA
void relatedAlsoRelated();

//! @relates classA classB
#define RELATED_MACRO related()

//! @relates classA
//! @relates classB
#define RELATED_MACRO_2 related2();

//! @relatedalso classA classB
#define RELATED_ALSO relatedAlso();

//! @relatedalso classA
//! @relatedalso classB
#define RELATED_ALSO_2 relatedAlso2();

//! @relates classA
//! @relatedalso classB
#define RELATED_RELATED_ALSO relatedRelatedAlso();

//! @relatedalso classA
//! @related classA
#define RELATED_ALSO_RELATED relatedAlsoRelated();

The only one that works is relatedAlsoRelated and, again, the macros do not work at all:

classA documentation:

classB documentation:

If the syntax has to be relatedAlso after related then that's fine, and really not a big issue at all, but it's a major problem that it doesn't work for macros.

[albert-github]

Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem?
Especially the configuration file is of importance as depending on some settings (PREDEFINED etc.) some results might be different.

[albert-github]

I think that in the documentation a small part is missing, the restriction regarding that just one and only one \relates, \relatesalso or \memberof can be used as indicated by the warning messages as well:

related.hpp:5: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:12: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:16: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:20: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:27: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:34: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:38: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:42: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition

The construct:
//! @relates classA classB
will see that the function relates to classA, classB will just be seen as normal text. The \relates command says that it can only have one argument.

relatedAlsoRelated works as here the \relatesalso and \relates both point to classA and only the last one is used.

Regarding the defines according what I see RELATED_ALSO_RELATED is also related as "function" to classA (due to the \relatedalso and \related both pointing to classA).

[Hyperlynx2]

Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem?
Especially the configuration file is of importance as depending on some settings (PREDEFINED etc.) some results might be different.

Attached: doxygen_issue_851.zip

I think that in the documentation a small part is missing, the restriction regarding that just one and only one \retlates, \relatesalso or \memberof can be used as indicated by the waring messages as well:

related.hpp:5: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:12: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:16: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:20: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:27: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:34: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:38: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition
related.hpp:42: warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition

The construct:
//! @relates classA classB
will see that the function relates to classA, classB will just be seen as normal text. The \relates command says that it can only have one argument.

I don't entirely follow. Isn't the ticket specifically to allow relating a function to more than one class? What would the correct syntax be? Or is this not implemented?

relatedAlsoRelated works as here the \relatesalso and \relates both point to classA and only the last one is used.

Oh whoops, of course that worked. Bad example on my part. That was supposed to test @relatedalso classA and @related classB.

[albert-github]

Indeed looks like the issue is to implement the possibility of multiple \relates etc. The fix only gives a warning to reflect the current behavior i.e. only one \relates etc. possible per function (as also indicated in my comment of 2018-06-16 17:12:55)

The problem of multiple \relates etc. per function is currently not implemented, I'll reopen the issue for this.

[luketpeterson]

++ This is a very important feature. Otherwise I can't see a way to list all the functions that interact with a type on that type's documentation page. (C API docs)

[scott-zhong]

I think the change made to fix this has introduced a regression for \relates on with more than one grouping. The warning warning: found multiple \relates, \relatesalso or \memberof commands in a comment block, using last definition showed up with Doxygen 1.8.15 and continues to occur even on trunk 1.11.0 (5fa510c*)

testcase:
testcase.zip