16

I have a C++ templated class base::Foo<class T>, and I have in another file a class base::bar::Foo : public base::Foo<Baz>. Doxygen seems not to like this, as it throws an error

<unknown>:1: Detected potential recursive class relation between class snLib::mocTwod::DsaCell and base class DsaCell< snLib::mocTwod::ProblemTraits, detLib::cellDiffusionTwod::ProblemTraits >!

Is there a way to prevent this from occurring? Doxygen's documentation doesn't talk about this error or anything about "potential recursive class relation"s.

The "base" class:

/*! \file snlib/DsaCell.hpp
 */
#ifndef snlib_DsaCell_hpp
#define snlib_DsaCell_hpp
#include "Dsa.hpp"

namespace snLib {
/*!
 * \brief  Implementation of naive cell-centered DSA
 */
template <class HoTraits_T, class LoTraits_T>
class DsaCell : public snLib::Dsa< HoTraits_T, LoTraits_T >
{
    [snip]
};
}
#endif

one of its descendants that is causing the problem:

/*! \file snlib/twod/moc/DsaCell.hpp
 */
#ifndef snlib_twod_moc_DsaCell_hpp
#define snlib_twod_moc_DsaCell_hpp
#include "snlib/DsaCell.hpp"

#include "ProblemTraits.hpp"
#include "detlib/twod/celldiffusion/ProblemTraits.hpp"

namespace snLib { namespace mocTwod {
/*!
 * \brief Inconsistent DSA for MOC
 */
class DsaCell : public snLib::DsaCell<
                        snLib::mocTwod::ProblemTraits,
                        detLib::cellDiffusionTwod::ProblemTraits
                        >
{
    [snip]
};
} } // end namespace snLib::mocTwod
#endif

My Doxygen configuration file has many options set, including the path configuration: STRIP_FROM_PATH (set to the root directory), STRIP_FROM_INC_PATH (same), INCLUDE_PATH (same).

Edit: it looks like the error was actually thrown in another Doxyfile that used the XML tags generated by the one with the conflicting name, so the problem was related to that. Anyway, I just renamed the base class to something else and all was well again.

Seth Johnson
  • 14,762
  • 6
  • 59
  • 85
  • 2
    Report a bug, but really nested names are allowed to conflict in order to accommodate asynchronous development by different teams. Reusing the same name on purpose is still discouraged, even if the language allows it. – Ben Voigt Mar 02 '11 at 04:57
  • 1
    You should post your exact code, rather than a synthesized version of it. Are you fully qualifying the base class? – David Rodríguez - dribeas Mar 02 '11 at 08:42
  • @Ben: Thanks for the suggestion; I might just rename the base class. – Seth Johnson Mar 02 '11 at 13:20
  • 1
    @David: I thought I'd post a general description first in case this is a known issue, because people generally balk at large chunks of code. :P I'll update my answer, but I doubt it will be very helpful. – Seth Johnson Mar 02 '11 at 13:21
  • @Seth Johnson: What doxygen version are u using? – Alok Save Apr 06 '11 at 06:12
  • @Als: I'm using Doxygen 1.7.2. – Seth Johnson Apr 06 '11 at 12:18
  • It's true that nested names are allowed to conflict, but I agree with you that you should probably rename the base class. My personal rule of thumb is that language-allowed name conflicts are acceptable as long as the two classes don't actually interact, but if they do, it can be the source of some confusion (both for developers and, apparently, parsing software). – Reinderien Apr 10 '11 at 14:33
  • @SethJohnson Please disregard any advice to keep all class names unique. The point of namespaces is not to accommodate conflicts but to avoid them. Consider, for example, the class names in the `boost` namespace that coincide with `std`. OTOH, do be sure that your class names are accurate, e.g. by observing the 'is a' rule for classes: make sure that `snLib::mocTwod::DsaCell` *is a* `snLib::DsaCell`. – John McFarlane Jul 07 '19 at 09:04

1 Answers1

1

Doxygen has a function that check whether classes A and B have an inheritance relation (either direct or indirect), which is recursive. The function check the recursion for a limit depth of 256.

Probably doxygen is confused with your code (since the name coincidence) and think that class A depends on B and B depends on A again.

It could be a Doxygen bug, but the best approach can be rename the class.

robermorales
  • 3,293
  • 2
  • 27
  • 36
  • 1
    Restricting your choice of class names in response to poor-quality tooling seems like a bad idea to me. – John McFarlane Jul 07 '19 at 08:37
  • @JohnMcFarlane did you do some research and tested the problem with the current doxygen version? Have you been able to reproduce the old (doxygen 1.7.2) behavior? PLease show the code you used to reproduce the problem. – albert Jul 07 '19 at 09:29
  • @albert [Reproduction of failure with 1.8.11](https://travis-ci.org/johnmcfarlane/cnl/jobs/555698315#L1673). [Branch used to reproduce](https://github.com/johnmcfarlane/cnl/tree/so7498072). Confirmed with version 1.8.13. – John McFarlane Jul 08 '19 at 10:22
  • I just tried with the 1.8.11, 1.8.13 version and the master version taking the repository (develop branch) as given and taken a clean Doxyfile (only setting RECURSIVE to YES and catching the warnings in a file). and got for both versions 3 "recursive" warnings but not the one indicated in the "Reproduction of failure with 1.8.11". The file include/cnl/_impl/integer/numeric_limits.h is in my case just 31 lines, do I need a special branch? – albert Jul 08 '19 at 10:47
  • The first recursive warning I get is: `include/cnl/rounding_integer.h:270: warning: Detected potential recursive class relation between class std::numeric_limits< cnl::rounding_integer< Rep, RoundingTag > > and base class numeric_limits< cnl::rounding_integer< Rep, RoundingTag > >!` – albert Jul 08 '19 at 10:47
  • Just tried the `so7498072` branch and here I get message as reported. Best is to create an issue at https://github.com/doxygen/doxygen/issues/new with attached a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent. – albert Jul 08 '19 at 11:02
  • @albert I've given you an example you were able repro and you still want me to take the time to reduce the example and submit it to a project with 1999 open issues? Thanks, but I would much rather spend that time migrating to a better documentation generator. – John McFarlane Jul 25 '19 at 07:19
  • @JohnMcFarlane The question here on stackexchange are not recorded in a bug tracing system and will as such not get to / remain with doxygen developers. Searching in a large program for where the problem does occur is a tedious and very time consuming work and ca greatly be reduced when the submitter reduces the problem to a, possible, minimal example. – albert Jul 25 '19 at 08:18
  • @JohnMcFarlane As you mention the number of open issues, around 220 have been triaged and resolved / solved in the mean time (and a number of them have a pull request and are not in a solved state till they are integrated into the master branch. Still there are quite a lot open issues, but you will also have seen that there are quite a few pull request with possible solutions and since the last release quite a few pull requests have been integrated into master. So Yes please creat a minimal example. – albert Jul 25 '19 at 08:19