Feature request: new config option for \headerfile output

[jwakely]

The SHOW_INCLUDE_FILES option seems to control two things. It causes the relevant header for a class to be shown in the docs for that class, and it also shows which header files a file includes in the docs for that file.

For example, SHOW_INCLUDE_FILES=YES for a class shows:

std::error_condition Class Reference
#include <system_error>

And for a file it shows:

system_error File Reference

#include <bits/c++config.h>
#include <bits/error_constants.h>
#include <iosfwd>
#include <stdexcept>
#include <bits/functional_hash.h>
Go to the source code of this file.

I want to be able to get the first effects, without the second. I do want to display the correct header that should be included for the definition of each class (that is an important part of the user-facing API that I want to document). But I don't want to show which files are included by each of my files (that is an implementation detail and not something I want the user-facing documentation to show).

It seems that there is one config option that conflates these two things, only one of which is documented:

SHOW_INCLUDE_FILES

If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of the files that are included by a file in the documentation of that file.

The default value is: YES.

Could there be a new config option to control whether the header for a class is shown in the class' docs?

Also, could \headerfile be supported for arbitrary comment blocks, not only classes and unions? I have non-member functions which are defined in some internal header file such as <bits/unique_ptr.h>, but I want to document that some other header such as <memory> is the correct way to get the definition of std::make_unique.

[jwakely]

As a workaround I can decorate the includes in the file like this:

/// @cond undocumented
#include <bits/c++config.h>
#include <bits/error_constants.h>
#include <iosfwd>
#include <stdexcept>
/// @endcond

And now they will only get shown if I use ENABLED_SECTIONS=undocumented but it would be better if that wasn't necessary (I'm already having to compromise the readability of the code to work around various doxygen quirks, I'd rather not add more).

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue, it was now automatically closed due to the linked pull request, 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.9.2.
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).