@file and @headername directives

[Jonathan Wakely]

On Fri, 23 Aug 2024 at 21:13, Jonathan Wakely <jwakely@redhat.com> wrote:
>
> On Fri, 23 Aug 2024 at 19:39, Kim Gräsman <kim.grasman@gmail.com> wrote:
> >
> > Thank you!
> >
> > On Sun, Aug 18, 2024 at 7:50 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> >>
> >>
> >> I wouldn't be opposed to it though. IWYU is a nice tool and I'd love if it worked well with our headers. If being a bit more regular would help you, even if it's not strictly needed for doxygen, that seems like a reasonable change. As long as doxygen still works of course.
> >
> >
> > I've played around with this a bit after working through getting GCC and libstdc++ built. I found this page, which describes nicely the prerequisites and available doc targets: https://gcc.gnu.org/onlinedocs/libstdc++/manual/documentation_hacking.html.
> >
> > Unfortunately I haven't been able to find a working Doxygen 1.7.6.1 -- is that still the only supported version? My Ubuntu appears to come with 1.9.1, so I don't think that qualifies for testing.
>
> No, I think that's supposed to be a minimum version, not an exact requirement.
>
> As you can see in the footer of
> https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html
> I used 1.9.5 last time I generated those pages.
>
> I think we actually depend on some bug fixes and new features added
> around the 1.9.1 time frame, so 1.7.6.1 will give bad results anyway.

Doxygen 1.9.2 includes a patch I made to improve libstdc++ docs:
https://github.com/doxygen/doxygen/issues/8639
And also fixed this:
https://github.com/doxygen/doxygen/issues/8638
1.9.3 fixed:
https://github.com/doxygen/doxygen/issues/8755
1.9.5 fixed:
https://github.com/doxygen/doxygen/issues/9211

But 1.9.1 will still work, it just won't generate output that's quite as good.

I'd update the libstdc++ docs to give 1.9.5 as the minimum, except
that probably isn't a good idea if Ubuntu only has 1.9.1. I'll say
1.9.1 as a minimum though.