SHOW_HEADERFILE doesn't work well for headers with no file extension

[jwakely]

Describe the bug

With this config:

SHOW_HEADERFILE=YES
EXTENSION_MAPPING      = no_extension=C++ \
                         .h=C++

the description for every C++ class defined in a header file foo.h will show:

#include <foo.h>

This happens whether the classes have \headerfile in their comments or not. And if you use @headerfile foo it will show #include <foo> instead. Great.

But C++ classes defined in a file with no extension, e.g. bar, will not show their header file by default. You have to use \headerfile to get them to display the #include <bar> info. This is inconsistent.

The point of \headerfile is to be able to "correct" the header shown for SHOW_HEADERFILE, when the file that the class is actually defined is some implementation details like detail/foo.h and the public API says to include <bar> instead. So you use \headerfile bar to make the class display the right header.

But when the class is already defined in the same header that users should actually include, you usually don't need to specify \headerfile, you just let Doxygen infer it correctly and display #include <foo.h>. This doesn't work if the file has no extension, so you need to add an explicit \headerfile bar to every class in file bar. Why? Is it because a file with no extension is being treated as a source file, not a header file?

Expected behavior

A class defined in a file with no extension should infer its \headerfile to be the filename, and show that in the SHOW_HEADERFILE info.

If the problem is that an extension-less file like bar is assumed to be more like bar.cc than bar.h, could we maybe get a way to say that a given file is header-like not source-like? Maybe an extension (no pun intended) to EXTENSION_MAPPING so that we can say no_extension=C++hdr instead of no_extension=C++?

Or maybe something on the \file for bar that could say "treat this file like a header, and so every class defined in the file has an implied \headerfile bar. Maybe implementing #9334 would allow that, by giving a header-file or \headerfile in the \file comment block.

Screenshots

This shows the docs for three structs side by side. S and S2 are both in a file called bar with this content:

/// @file bar
/// This is a header file called `<bar>` (with no extension).

/// A struct in file `<bar>`
struct S { };

/// @brief Another struct in file `<bar>`
/// @headerfile bar
struct S2 { };

And struct X is defined in file foo.h with this content:

/// @file foo.h
/// This is a header file called `<foo.h>`

/// A struct in file `<foo.h>`
struct X { };

(These files are in the zip file attached below).

Observe that X shows its headerfile as #include <foo.h> even though there is no explicit \headerfile command, but S does not show any header file info. S2 does show its header file info as #include <bar> but only because there's an explicit \headerfile for that class.

What I want is for S to show the info, without needing the explicit \headerfile bar naming the current file, because that seems redundant. Doxygen correctly infers the header file for the class in foo.h but not for the classes in bar.

To Reproduce

issue-10010.zip

Version

Same results with 1.9.5 and 1.9.6 (875558c) and 1.9.7 (48bb276)

[albert-github]

The problem comes from the fact that when the assignment of the include filename is done i.e. in doxygen.cpp in the code fragment:

    else if (includeFile.isEmpty() && ifd &&
        // see if the file extension makes sense
        guessSection(ifd->name())==Entry::HEADER_SEC)
    { // implicit assumption
      fd=ifd;
    }

there is also a guessSection that checks the extension and here we don't have an extension so the test on the section type is not fulfilled.

@doxygen would the be anything against either

• remove the complete test on guessSection or
• extend the test, in this case, by also allowing file names without extension

[jwakely]

The context is the libstdc++ docs for GCC. All standard C++ headers have no extension, e.g. <random> and <string>. So I need to add @headerfile to all classes in our internal implementation-detail headers like bits/basic_string.h but I also need to add @headerfile to all class defined directly in the correct headers, like <optional>. So I basically have to add @headerfile to every class in the standard library. That's a lot of classes :-)

[doxygen]

@doxygen would the be anything against either

* remove the complete test on `guessSection` or

* extend the test, in this case, by also allowing file names without extension

Since guessSection is also used at other places, maybe best to make it simply return HEADER_SEC for anything that is not detected as a SOURCE_SEC.

[albert-github]

@doxygen
Somewhere in the back of my mind I remember that there would be problems.
Looking at the code the suggestion of all that is not a source file according to the list is a header file would not work as this means that all Fortran files would be seen as header files as well.
Also, I think, it is possible that an include file has the extension .c (unusual but ...), so I think the best would be to remove the guessSection at the indicated place in doxygen.cpp.

[jwakely]

Would it make sense to make it depends on whether no_extension=C++ was used in the config? I think only C++ uses headers with no extension (but not only the std::lib, as other libs like Eigen do it too). But it no_extension=Fortran was used, assume source file not header.

[albert-github]

I've just pushed a proposed patch, pull request #10014

[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.9.7.
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).