C++ using directives are not understood (Origin: bugzilla #617285)

[doxygen]

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

On 2010-04-30 13:39:06 +0000, Yann Leprince wrote:

C++ using directives are not understood. For example in the following code,
the  generated documentation contains an entry for A::var but no entry for
B::var. Adding "/// \brief The using directive" right before the using
directive does not change the output.

This behaviour contradicts the meaning of this C++ code: the variable is
made available in both namespaces.

My feeling is that an entry for var should be generated in the documentation
of namespace B, containing a pointer to the documentation of var in
namespace A. In addition, if a documentation block corresponds to the using
directive, its contents should appear in the documentation of B::var as well
as the pointer to the documentation of A::var.


/// \brief Namespace containing a real variable
namespace A {
  /// \brief The variable
  int var;
}

/// \brief Namespace containing using directive
namespace B {
  using A::nb;
}

[rsivek]

Having Doxygen handle using directives in this manner is also valuable for class declarations which expose base class member functions via the using directive, as outlined in this SO question.

[bradenmcd]

This issue should probably be renamed. What both @nanowizard and the original reporter are describing are accurately called "using declarations". A using directive occurs at file/namespace scope and looks like:

using namespace foo;

There is probably not much value in having Doxygen understand those.

[robch]

I would really love to have this issue fixed, because without it I'm going to have to do very unnatural things to keep using doxygen in our project.

[albert-github]

@robch

• Which version of doxygen did you try? (As there might already be some improvements in the newer versions)
• Can you please attach 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.

[eramongodb]

This issue should probably be renamed.

This effects all types of using that import declarations of entities from one namespace into another.

Which version of doxygen did you try? (As there might already be some improvements in the newer versions)

There have been no notable improvements since the comment above, and the (fixed) example given in the original 2010 report still fails exactly as described:

/// \brief Namespace containing a real variable
namespace A {
  /// \brief The variable
  int var;
}

/// \brief Namespace containing using directive
namespace B {
  using A::var; // <-- This is completely missing in Doxygen results.
}

This issue is still present in the latest Doxygen release (1.9.8) and is reproducible by running doxygen -g && doxygen in a directory containing just a header file with the contents above.

There is probably not much value in having Doxygen understand those.

As shown in the example below, it can directly impact the quality of generated documentation in any circumstance where the imported declarations are intended to be part of the documented interface (which is presumably why the using-declaration or using-directive is present to begin with).

Can you please attach a, small, self contained example

Here is a more detailed example comparing the generated documentation for two headers that both simulate ABI symbol versioning:

/// \file ok.hpp Demonstrates desired Doxygen behavior.

/// Generates the desired Doxygen results.
namespace with_inline {
  /// ABI version 1.
  inline namespace v1 {
    /// This is the current `with_inline::S`.
    struct S {};
  }

  /// ABI version 2.
  namespace v2 {
    /// This is an upcoming `with_inline::S`.
    struct S {};
  }
}

/// \file not_ok.hpp Demonstrates the using-declaration issue.

/// Generates undesirable Doxygen results.
namespace with_using {
  /// ABI version 1.
  namespace v1 {
    /// This is the current `with_using::S`.
    struct S {};
  }

  /// ABI version 2.
  namespace v2 {
    /// This is an upcoming `with_using::S`.
    struct S {};
  }

  using v1::S; // <-- This is completely missing in Doxygen results.
}

As before, the issue is reproducible with the latest Doxygen release (1.9.8) by running doxygen -g && doxygen in a directory containing just these two header files.

The ok.hpp header generates a namespacewith__inline.html page that looks as follows:

Generates the desired Doxygen results.

Namespaces

• namespace v1: ABI version 1
• namespace v2: ABI version 2

Classes

• struct S: This is the current with_inline::S.

Detailed Description

Generates the desired Doxygen results.

The not_ok.hpp header generates a namespacewith__using.html page that looks as follows:

Generates undesirable Doxygen results.

Namespaces

• namespace v1: ABI version 1
• namespace v2: ABI version 2

Detailed Description

Generates undesirable Doxygen results.

The with_using namespace page should have an entry mentioning "the current with_using::S" that redirects to the with_using::v1::S class page, just like how the with_inline namespace page has an entry that redirects to the with_inline::v1::S class page.

Similarly, the generated annotated.html page that lists documented classes looks as follows:

Here are the classes, structs, unions and interfaces with brief descriptions:

• N: with_inline: Generates the desired Doxygen results
  • N: v1: ABI version 1.
    • C: S: This is the current with_inline::S.
  • N: v2: ABI version 2.
    • C: S: This is an upcoming with_inline::S.
  • C: S: This is the current with_inline::S.
• N: with_using: Generates undesirable Doxygen results.
  • N: v1: ABI version 1.
    • C: S: This is the current with_using::S.
  • N: v2: ABI version 2.
    • C: S: This is an upcoming with_using::S.

The with_using namespace should have an entry mentioning "the current with_using::S" that redirects to the with_using::v1::S class page, just like how the with_inline namespace has an entry that redirects to the with_inline::v1::S class page.

Note, attempts to manually document the using-declaration also have no effect (even with explicit commands):

/// This should be documented!
using v1::S; // <-- This is completely missing in Doxygen results.

[bisht2050]

Hi @albert-github, any updates on this? Could we please fix this sooner than later?

[doxygen]

@bisht2050 I'll look into this. I agree this should be handled better.

[doxygen]

@bisht2050 Please verify if the referenced commit fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.

[eramongodb]

Thank you very much for the update.

Testing Doxygen with the reference commit (doxygen -v -> 1.13.0 (d067a7ffe6b2abe94595268487ca3461a62da0a5)) produces promising results. The cases described earlier in this issue now generate the expected output. However, there are still unresolved cases not yet being handled properly by Doxygen even with the referenced commit.

Each of the snippets below are standalone header files which may be used to reproduce the described issue (labeled with "Problem:") using doxygen -g && doxygen. Accompanying Doxygen warnings in command output are included.

---

/// \file
/// Problem: \ref B::foo is documented but not a valid reference.

/// Declares \ref A::foo.
namespace A {

/// Declared in \ref A.
void foo();

} // namespace A

/// Expecting B::foo.
namespace B {

using A::foo; // OK: documented in namespace page.

} // namespace B

header.hpp:2: warning: unable to resolve reference to 'B::foo' for \ref command

---

/// \file
/// Problem: \ref Y::foo is not documented but is a valid reference.

/// No parent namespace.
struct A {
    /// Member declared in A.
    void foo();
};

/// A parent namespace.
namespace N {

/// Declared in namespace \ref N.
struct B {
    /// Member declared in \ref N::B.
    void foo();
};

} // namespace N

/// Expecting \ref X::foo.
struct X : private A {
    using A::foo; // OK: "Expecting X::foo"
};

/// Expecting \ref Y::foo.
struct Y : private N::B {
    using N::B::foo; // Problem: missing in class page.
};

<no warnings or errors>

---

/// \file
/// Problem: \ref B::Y is not documented or a valid reference.

/// Declares X and Y.
namespace A {

/// X declared in A.
class X {};

/// Y declared in A.
class Y {};

} // namespace A

/// Expecting members X and Y.
namespace B {

using   A::X; // OK: "X declared in A."
using ::A::Y; // Problem: missing in namespace page.

} // namespace B

header.hpp:2: warning: unable to resolve reference to 'B::Y' for \ref command