Full scope needed when making link inside cross-referenced section [with test case] (Origin: bugzilla #740218)

[doxygen]

status RESOLVED severity normal in component general for ---
Reported in version 1.8.8-GIT on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

• xrefitem.zip (ID 290809)
• deprecated.html (ID 290811)
• [Bug740218 (2).zip](http://ftp.stack.nl/pub/users/dimitri/bugzilla/attachments//bug740218_290814_Bug740218 (2).zip) (ID 290814)
• xrefitem2.zip (ID 292995)

On 2014-11-16 19:51:17 +0000, Vladimír Vondruš wrote:

Created attachment 290809
Repro/test case

See attached ZIP file for minimal repro case or the following snippet:

namespace Foo {

/** @brief Structure */
struct Bar {
    /**
     * @brief Foo
     * @deprecated Use @ref bar() instead.
     */
    void foo1();

    /**
     * @brief Foo
     * @deprecated Use @ref Foo::Bar::bar() "bar()" instead.
     */
    void foo2();

    /** @brief Bar */
    void bar();
};

}

WHen generating docs, Doxygen compains about invalid reference on the deprecated page:

deprecated:2: warning: unable to resolve reference to `bar()' for \ref command

The first link is created correctly in the class documentation, but not on the Deprecated page (deprecated.html). When full scope is specified like in the second case, the link is correctly generated, but the workaround gets annoying when the scope is too long to write. This happens for all cross-referenced items, such as @todo, @bug and user-defined ones created with @xrefitem.

Would it possible for Doxygen to remember scope of each cross-referenced item when creating given page and resolve links relative to that scope?

Tested with current Git (9f477b8), but the issue appears for some time (I think
it was present already in 1.7).

On 2014-11-16 20:23:03 +0000, Kevin McBride wrote:

Created attachment 290811
HTML Page of Deprecated List

On 2014-11-16 20:47:52 +0000, Kevin McBride wrote:

I have the same problem with version 1.8.8. In addition, a search for similar bugs reveals that Doxygen has a problem with referencing functions in structs and classes within the namespace it is documenting.

I also put some code underneath bar(), named the function foo3(), and bar() is still not being referenced in deprecated blocks.

On 2014-11-16 20:52:02 +0000, Kevin McBride wrote:

Created attachment 290814
Edited Test Case

On 2014-11-17 19:44:52 +0000, Dimitri van Heesch wrote:

Confirmed. Should be fixed in the next GIT update.

On 2014-12-18 18:43:29 +0000, Vladimír Vondruš wrote:

Sorry for taking so long to reply, but the commit (c6e4122) caused an regression for me. The relative scope now works properly, but the output is broken in the following case (also included in the following attachment):

namespace MyNamespace {

template<class> struct Foo;

/** @todo Xrefitem works without issues */
template<class T> struct Foo<T> {};

/** @todo Xrefitem prints warning */
template<class T> struct Foo<Bar<T>> {};

}

When processing the file, Doxygen prints the following output (in other words, fully-scoped name of the documented template specialization, character by character):

todo:2: warning: Unexpected character `M'
todo:2: warning: Unexpected character `y'
todo:2: warning: Unexpected character `N'
todo:2: warning: Unexpected character `a'
todo:2: warning: Unexpected character `m'
todo:2: warning: Unexpected character `e'
todo:2: warning: Unexpected character `s'
todo:2: warning: Unexpected character `p'
todo:2: warning: Unexpected character `a'
todo:2: warning: Unexpected character `c'
todo:2: warning: Unexpected character `e'
todo:2: warning: Unexpected character `:'
todo:2: warning: Unexpected character `:'
todo:2: warning: Unexpected character `F'
todo:2: warning: Unexpected character `o'
todo:2: warning: Unexpected character `o'

In addition to this warning, in the cross-reference list (in this case the TODO list), the following is displayed:

Bar< T > > Class MyNamespace::Foo< Bar< T > >

instead of just:

Class MyNamespace::Foo< Bar< T > >

To be clear, the issue appears only when using template as template parameter in template specialization (very corner case, I know). When using non-templated type as template parameter (the first case), it works properly. Also it doesn't matter if the class is enclosed in namespace or not.

The issue is not present in the parent commit (9f477b8) and is still present in current master (b3c44e5).

Thanks a lot!

On 2014-12-18 18:44:18 +0000, Vladimír Vondruš wrote:

Created attachment 292995
Repro/test case for the regression

On 2014-12-19 05:17:38 +0000, Kevin McBride wrote:

I tested attachment in comment # 6 with the release version of 1.8.8 to verify the output. The output is okay, and I turned off quiet to verify there were no warnings. Unfortunately, I have not yet found a way to compile 1.8.8-GIT on my Windows laptop, despite a request on bug 697511 to get the necessary files to get Visual Studio to compile doxygen.

On 2014-12-19 10:25:55 +0000, Dimitri van Heesch wrote:

Regression confirmed. Should be fixed in the next GIT update.

On 2014-12-25 16:03:41 +0000, Dimitri van Heesch wrote:

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

[UBehrens]

I have made a similar observation with an architecture in a SW_system, heavily based on traits. To explain the problem, let me briefly show my code (not the actual one, but something similar):

namespace NS {
  namespace HTTP {
    template <typename T> struct HttpServer; // This is an abstract interface only

    template <typename T>struct Library { // This defines my generic traits, but only in terms of T
        typedef T                 CoreType;
        typedef Library<T> LibType; // ....
    };

    // Here comes the real thing: The specific HttpServer, which is based on the Library traits 
    template <typename T> struct HttpServer<Library<T>> {
        typedef typename Library<T>::CoreType CoreType;
        typedef typename Library<T>::LibType    LibType;
    };
  };
};

The idea is, that whatever types I used to define 'Library', they will be forwarded into 'HttpServer' under the proper names and that the only way to provide an instance of 'HttpServer' is, to write a corresponding specialization of 'Library'. In the real world, the entire system is even a bit more complicated, but that's not my issue here. My point is the following: Assume that the specialization of 'HttpServer' also has the following enum and virtual function:

    template <typename T> struct HttpServer<Library<T>> {
        typedef typename Library<T>::CoreType CoreType;
        typedef typename Library<T>::LibType    LibType;

        enum HTTP_SERVER_STATUS {
            STATUS_OK,
            STATUS_ERROR
        };
            
        virtual HTTP_SERVER_STATUS worker_status(void) const;
    };

I now expect the following to be valid C++

    class MyClass : public HttpServer<MyClass> {

     /**
       *  \return \ref STATUS_OK, in one case, otherwise return 
       *              \ref HttpServer<Library<MyClass>>::STATUS_ERROR
       */
      virtual HTTP_SERVER_STATUS worker_status(void) const override { return .....; }
    };

and this is accepted and properly compiled by g++-17 in all recent versions. However at least doxygen 1.8.15 refuses any way of documenting 'worker_status()'. The above ones are just some simple examples and I have tried various other combinations, including namespaces (all completely documented) and have also received additional error messages along 'warning: explicit link request to 'STATUS_ERROR' could not be resolved'.

Any ideas? Your help is appreciated!

Best regards, Uwe

[albert-github]

• What is the relation with the original issue?
• What happens with the current version of doxygen (1.9.1)
• When the problem is still present in 1.9.1, best to open a new issue 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.

[UBehrens]

Hello! Please let me apologize, if I did not provide enough information in my original posting or did not do it the proper way. Since this is/was my first comment on an already closed discussion, I was not sure how to draw attention to my problem, including to maybe unintentionally re-opening an issue by accident. That's why I just described the situation I faced without following proper procedure. Please also excuse my bad english, this is not my native language... The issue is, that I am facing error messages for items like STATUS_OK or STATUS_ERROR like these: warning: explicit link request to 'STATUS_ERROR' could not be resolved warning: unable to resolve reference to 'STATUS_OK' for \ref command at least partially described just like the originally described by the original poster of the thread. Whether I get one or the other depends on whether I try to use a \ref command. Either way, the symbols can not be found, although they are defined in the base class in a proper and accessible way, yet difficult to find (which is, what I wanted to describel). Numerous other people have at least until 2020 described comparable difficulties. Unfortunately, I have until today not been able to upgrade my work version of doxygen to 1.9.1, so I can not exactly describe any changes here, however I was hoping somebody in the community had been aware of the problem and recent behaviourial changes. My observation has been in the past, that doxygen often had some problems resolving names, in particular when it comes to dependent namespaces, template specializations and other really nasty stuff. Don't get me wrong, it's a wonderful tool and I really love it, the question is 'How do I have to write the name in order to give doxygen a chance to recognize it?' Again, let me excuse my bad approach. Unless this is a well known issue, I will try to upgrade here to 1.9.1 first and then try again to inform you with my results. Thanks for your time.

-- ------------------------- Uwe Behrens <uwe@ubehrens.de> Am 18.01.2021 19:17, schrieb albert-github:

* What is the relation with the original issue? * What happens with the current version of doxygen (1.9.1) * When the problem is still present in 1.9.1, best to open a new issue 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. -- You are receiving this because you commented. Reply to this email directly, view it on GitHub [1], or unsubscribe [2].

Links: ------ [1] #5678 (comment) [2] https://github.com/notifications/unsubscribe-auth/AORPWCPBI66FTYDQ6YJ3QETS2R3MZANCNFSM4FH4NODQ

[albert-github]

Best is that you open an new issue wit:

• 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.

So we can see what you have done in 1.8.15 (and we can see what the difference will be in 1.9.1).