HIDE_SCOPE_NAMES does not hide names in Modules list or @ref link text

[MarkCallow]

Describe the bug I am documenting an object-oriented c API implemented with pseudo classes with function names of the form ClassName_MethodName. I use \class ClassName when documenting the "class" structure and \memberof ClassName in the documentation for each of the functions. The functions are also part of a module created with \defgroup. In the list of functions at the top of the module's page and in the list of functions under "Modules" in the ToC the functions are listed as ClassName::ClassName_MethodName. Clearly undesirable and a surprise since OPTIMIZE_OUTPUT_FOR_C = YES is set in my configuration.

If I set HIDE_SCOPE_NAMES = YES in my configuration then ClassName:: disappears from the function list at the top of the module's page but still appears in the table of contents and in the link text of any external \ref to any "member" of the class.

Expected behavior

HIDE_SCOPE_NAMES = YES would hide scope names everywhere. OPTIMIZE_OUTPUT_FOR_C = YES would hide scope names related to \memberof commands as those are clearly documented as for use in languages that do not support classes and therefore would not understand ClassName::.

Screenshots

Here is a shot showing the expanded Modules list and the top of the page for the "Reader" module. This was generated with HIDE_SCOPE_NAMES = YES.

Here is a shot showing the link text for a \ref

I can fix this using explicit link text as also shown but it makes the link very cumbersome.

To Reproduce

Here's a zip containing a configuration file and single source file that demonstrates the problem. Run doxygen Doxyfile.libktx.doc to build the output then look at html/index.html. Change HIDE_SCOPE_NAMES to NO if you wish to see the scope names listed at the top of the "Reader" module page.

hide_scope_names.zip

Version 1.9.6 macOS and Windows. It's probably been happening in 1.9.3 and earlier but I did not try HIDE_SCOPE_NAMES = YES in any other version.

[albert-github]

To the best of my knowledge:

The documentation of the OPTIMIZE_OUTPUT_FOR_C states:

Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources only. Doxygen will then generate output that is more tailored for C. For instance, some of the names that are used will be different. The list of all members will be omitted, etc.

I your code you use some none C constructs in the documentation so it is not that surprising that a class name is shown, the OPTIMIZE_OUTPUT_FOR_C tag doesn't change the content but just some terminology.

Regarding the shown class name, which comes from (whin I'm not mistaken):

/**
 * @brief Show HIDE_SCOPE_NAMES issue
 *
 * A reference like @ref ktxTexture2.ktxTexture2_CreateFromStdioStream is
 * rendered with the scope name regardless of the setting of
 * HIDE_SCOPE_NAMES. To avoid the scope name, reference like this
 * @ref ktxTexture2.ktxTexture2_CreateFromStdioStream
 * "ktxTexture2_CreateFromStdioStream".
 */
void
showHideScopeNamesIssue()
{
}

When we lo0k at the documentation of \ref we see:

24.113 \ref ["(text)"]

Creates a reference to a named section, subsection, page or anchor. For HTML documentation the reference command will generate a link to the section. For a section or subsection the title of the section will be used as the text of the link. For an anchor the optional text between quotes will be used or if no text is specified. For LATEX documentation the reference command will generate a section number for sections or the text followed by a page number if refers to an anchor.

The essential part her is:

For an anchor the optional text between quotes will be used or if no text is specified.

and at that moment the specified name (in your case ktxTexture2.ktxTexture2_CreateFromStdioStream) is used as text as well so it is not surprising that the class name is shown (and you need here the class name due to the usage of the \class command).

I think the issue is usage (interpretation) but I didn't yet apply that label.

@ doxygen what do you think?

[MarkCallow]

@albert-github thank you for your response.

your code you use some none C constructs in the documentation so it is not that surprising that a class name is shown, the OPTIMIZE_OUTPUT_FOR_C tag doesn't change the content but just some terminology.

My note about the documentation was in connection to the \memberof command not OPTIMIZE_OUTPUT_FOR_C.

This command makes a function a member of a class in a similar way as \relates does, only with this command the function is represented as a real member of the class. This can be useful when the programming language does not support the concept of member functions natively (e.g. C).

I read this as saying there is no need to use this command when the language supports real classes. Therefore when it is used it is not a good idea to output some other language's class construct.

I concede that what OPTIMIZE_OUTPUT_FOR_C is supposed to do is not clearly documented.

What you say about \ref is true. I can live with the way it operates because it is easily worked around. This appeared because in 1.9.3 \ref ktxTexture2_CreateFromStdioStream worked but in 1.9.6 a "reference not found" warning is raised. Fixing this necessitated using the fully qualified name, ktxTexture2.ktxTexture2_CreateFromStdioStream. Is this a regression or an intentional change?

The focus of this issue is to fix the "Modules" ToC function list when HIDE_SCOPE_NAMES = YES.

[albert-github]

The \memberof documentation says:

24.34 \memberof

This command makes a function a member of a class in a similar way as \relates does, only with this command the function is represented as a real member of the class. This can be useful when the programming language does not support the concept of member functions natively (e.g. C).

So here, I think, the same reasoning is valid as for the \class is valid especially as there is a \class used to map the member to.

I read this as saying there is no need to use this command when the language supports real classes. Therefore when it is used it is not a good idea to output some other language's class construct.

I concede that what OPTIMIZE_OUTPUT_FOR_C is supposed to do is not clearly documented.

The \class command is actually introduced to be able to document a class at another place than directly before the class definition. Indeed at some places the documentation can be improved (proposed pull requests with documentation updates are welcome).

I don't get the line:

The focus of this issue is to fix the "Modules" ToC function list when HIDE_SCOPE_NAMES = YES.

is this about the necessity of ktxTexture2 as shown in the example showHideScopeNamesIssue() or is there another place where the extra ktxTexture2:: shows (I didn't see it)?

Is this a regression or an intentional change?

I'm not sure this is an intentional change but I can imagine it is due to some stricter rules implemented in respect to resolving function names in relation to scopes (@doxygen ?).

[MarkCallow]

The focus of this issue is to fix the "Modules" ToC function list when HIDE_SCOPE_NAMES = YES.

is this about the necessity of ktxTexture2 as shown in the example showHideScopeNamesIssue() or is there another place where the extra ktxTexture2:: shows (I didn't see it)?

Look at the left hand pane of the first image I posted. All the function names in the list are prefixed with ktxTexture2::. The functions in the list in the right hand pane were similarly prefixed until I set HIDE_SCOPE_NAMES = YES. That configuration parameter should be removing them from the list in the left-hand pane too.

[albert-github]

I must have overlooked it, looks like it was introduced in version 1.9.2

[albert-github]

Regarding the scope names in the treeview I've just pushed a proposed patch, pull request #9924

[albert-github]

Code regarding the scope names in the treeview has been integrated in master on GitHub

[MarkCallow]

Sorry for the long long delay. I can verify that scope names are now hidden in treeview.

Rendered @refs still include the scope name as explained here.

/**
 * @brief Show HIDE_SCOPE_NAMES issue
 *
 * A reference like @ref ktxTexture2.ktxTexture2_CreateFromStdioStream is
 * rendered with the scope name regardless of the setting of
 * HIDE_SCOPE_NAMES. To avoid the scope name, reference like this
 * @ref ktxTexture2.ktxTexture2_CreateFromStdioStream
 * "ktxTexture2_CreateFromStdioStream".
 */
void
showHideScopeNamesIssue()
{
}

Do you want me to open a different issue for that and close this one?

[albert-github]

Sorry for the long long delay. I can verify that scope names are now hidden in treeview.

No problem, I was amazed though that this issue was still open.

When using the original example I can reproduced this problem also with the current doxygen version (1.12.0), one can see it easily when one uses the search field and searches for 'showHideScopeNamesIssue'.

I think it might make sense that also for references to classes / namespaces / functions the scope name is removed with the \ref command when HIDE_SCOPE_NAMES is set.

For this problem I've just pushed a proposed patch, pull request #11075

• are there other issues here that I've missed?

[MarkCallow]

Wow! Thanks for the quick response @albert-github.

are there other issues here that I've missed?

None that I am aware of w.r.t scope names.

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

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