@file and @headername directives

[Kim Gräsman]

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.

Thank you,
- Kim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://gcc.gnu.org/pipermail/libstdc++/attachments/20240823/94554042/attachment.htm>