Use `\headerfile` directive in doxygen documentation to indicate public header to include for functionality

[msimberg]

See https://www.doxygen.nl/manual/commands.html#cmdheaderfile.

[gformisa]

Hello team, It's my first tentative to work with good first issue. Which is the issue exactly ? What I should do to fix it ?

Thank you in advance to involved me :)

[msimberg]

Hey, thanks for having a look at this. I'll admit I don't know yet if this will necessarily be a useful thing to implement, but I opened the issue to find out!

1. As far as I understand, the idea with \headerfile is to document which header should be included to get that particular functionality. In the trivial case it sounds like this isn't necessary, since you just include the file which defines the functionality. However, in pika we define a smaller set of headers to actually be our public "API" (https://pikacpp.org/api.html). This allows us to rearrange things internally without affecting users. For example, split_tuple is defined in https://github.com/pika-org/pika/blob/main/libs/pika/execution/include/pika/execution/algorithms/split_tuple.hpp but we want users to include pika/execution.hpp. This is what I had in mind when I opened the issue.
2. A possible starting point would be to mark all the std::execution algorithms (like split_tuple: https://github.com/pika-org/pika/blob/ca48d55f90eabc3b51ae499fc07b15fe7b516460/libs/pika/execution/include/pika/execution/algorithms/split_tuple.hpp#L554-L563) with \headerfile <pika/execution.hpp>.
3. Perhaps most importantly, I don't know yet how \headerfile shows up in sphinx/breathe documentation, or if it can be made to show up there. Currently we document functionality under an explicitly created heading for a particular header (e.g. https://pikacpp.org/api.html#pika-execution-hpp). This last point is perhaps the most critical if this is to be useful at all.

Let me know if that makes sense or if that still sounds interesting. This is intentionally quite a vague issue and we don't yet how useful \headerfile could be, so would require some further investigation to see if it useful.