Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

@ref links are incorrect when used in class methods body #10869

Closed
AlexTr opened this issue May 16, 2024 · 5 comments
Closed

@ref links are incorrect when used in class methods body #10869

AlexTr opened this issue May 16, 2024 · 5 comments

Comments

@AlexTr
Copy link

AlexTr commented May 16, 2024

Describe the bug
When \ref is used inside class method, it generates link to source code files which are actually missing, the same \ref in standalone function body generates correct links

Screenshots
Screenshot 2024-05-16 at 20 31 48

To Reproduce
Create file with the following contents:

<?php
/**
 * @defgroup    CoreClasses Core Classes
 * @{
 */

/**
 * Sample class
 */
class FooClass {

    /** 
     * @anchor anc_foo_method_with_desc_above
     * Sample class method
     * @reminder @ref anc_foo_method_with_desc_above
     */
    public function foo_method_with_desc_above() {
        return 111;
    }

    public function foo_method_with_desc_below() {
        /**
         * @anchor anc_foo_method_with_desc_below
         * Sample class method
         * @reminder @ref anc_foo_method_with_desc_below
         */
        return 222;
    }

}

/** @} */

Run Doxygen 1.10.0 with the following config:

PROJECT_NAME           = BUGREPORT2
GENERATE_TREEVIEW      = YES
ALIASES                = "reminder=\xrefitem reminder \"REMINDER\" \"Reminders index\""
GENERATE_LATEX         = NO

Expected behavior
When method/function description is in function/body it should be treated the same way as in front of function/method definition and to work the same way, link should be correct and refer to the specified anchor.

Version
Ubuntu 20.04
Doxygen 1.10.0 (with oloder version the behaviour is the same)

Additional context
Minimal reproducible example is also attached.
test.tgz

@albert-github
Copy link
Collaborator

Difficult problem as we have here to do with "internal" documentation.
The problem can also be shown by means of the smaller example:

/// \file

void foo_method_with_desc_inside() {
    /**
     * @anchor anc_foo_method_with_desc_inside
     * Sample class method
     * @ref anc_foo_method_with_desc_inside
     */
}
/**
 * @anchor anc_foo_method_with_desc_outside
 * Sample class method
 * @ref anc_foo_method_with_desc_outside
 */
void foo_method_with_desc_outside() {
}

and when running doxygen -d Sections we get:

Section = anc_foo_method_with_desc_inside, file = .../FooClass.h, title = , type = 7, ref =
Section = anc_foo_method_with_desc_outside, file = _foo_class_8h, title = , type = 7, ref =

so we see that the file / anchor (type = 7) for the inside function is not "translated".
At first sight this would be according to the idea of "internal" documentation, though adding the \internal command and the setting INTERNAL_DOCS=YES still gives the same problem!

We also have the strange phenomenon that there is no warning like:

.../FooClass.h:3: warning: Member foo_method_with_desc_inside() (function) of file FooClass.h is not documented.

that should be present when there is no documentation for the function.

So I think the problem is that the \anchor command was not foreseen in "internal" documentation and thus is not handled (yet).

Looks like relevant type of functions are:

  • findSectionsInDocumentation in different files (*def.cpp)
  • docFindSections in different files (*def.cpp and docparser.cpp)
  • DocTokenizer::findSections

@doxygen any idea on how to tackle this problem?

Small example: example.tar.gz

@AlexTr
Copy link
Author

AlexTr commented May 17, 2024

Thank you @albert-github for taking care of this issue, it looks like you are correct with you assumption about \anchor command, also there is another issue with the same problem - #9663

@doxygen
Copy link
Owner

doxygen commented May 17, 2024

@AlexTr 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.

@AlexTr
Copy link
Author

AlexTr commented May 18, 2024

@doxygen Thank you a lot for quick fix 🙏 it works correctly now!

@albert-github albert-github added the fixed but not released Bug is fixed in github, but still needs to make its way to an official release label May 18, 2024
@doxygen
Copy link
Owner

doxygen commented May 20, 2024

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.11.0.
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).

@doxygen doxygen removed the fixed but not released Bug is fixed in github, but still needs to make its way to an official release label May 20, 2024
@doxygen doxygen closed this as completed May 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants