@file and @headername directives

[Jonathan Wakely]

On Fri, 23 Aug 2024 at 21:31, Kim Gräsman <kim.grasman@gmail.com> wrote:
>
> On Fri, Aug 23, 2024 at 10:13 PM 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.
>
>
> Thanks -- I managed to cobble together a working 1.7.6.1, so I tried building 'make doc-html-doxygen' with:
>
> * 1.7.6.1 on master
> * 1.7.6.1 on patch (with 'include/' removed)
> * 1.9.1 on master
> * 1.9.1 on patch
>
> And then 'git diff --no-index' the directories against each other to get an idea of differences.
>
> It does look like 1.7.6.1 fails to generate source pages if there is no include/ prefix. On the other hand some cross-references appear to be better picked up when include/ is removed.
>
> I _think_ 1.9.1 handles files similarly with or without include/, but I'm getting pretty sleepy now, so I can't tell for sure :-). Do you remember what a good test might be?
>
> I'll keep poking at this off and on, and might come back with a few patches.

I wouldn't waste your time with 1.7.6.1