doc: Expose all public headers

[TheEvilSkeleton]

Admittedly, it took me a good 30 minutes to understand why I couldn't use the instance methods for Xdp.Settings, which required me to dig through libportal's source code and realize that these methods aren't part of libportal/portal.h. I believe exposing all the public headers would help developers who want to use libportal.

---

• Steps to reproduce: #include <libportal/portal.h> (only) and try to call instance methods on XdpSettings
• Expected result: can do so
• Actual result: compiler errors because settings.h wasn't included

I also wrote a small reproducer: TheEvilSkeleton/Settings-Not-Included@8eb0714

[ebassi]

It's a bit naff, to be honest. I don't understand why there isn't a single header include for libportal, just like every other C library that depends on GLib. Single header inclusion makes it possible to move type declarations around without breaking source compatibility.

[smcv]

I don't understand why there isn't a single header include for libportal, just like every other C library that depends on GLib

There is, <libportal/portal.h>, but from @TheEvilSkeleton's report it seems that it's incomplete.

If fixing this is going to require a libportal source-code change anyway, probably including all of the libportal core headers in portal.h would be a better answer to this than changing the introspection?

(but not the GTK and Qt addons, those need to stay separate!)

[smcv]

Admittedly, it took me a good 30 minutes to understand why I couldn't use the instance methods for Xdp.Settings, which required me to dig through libportal's source code and realize that these methods aren't part of libportal/portal.h. I believe exposing all the public headers would help developers who want to use libportal.

It sounds like you're implicitly reporting a bug. What is the bug? It's usually better to describe the bug than making maintainers reverse-engineer it from a proposed fix, particularly in projects that are limited by maintainer bandwidth.

Presumably something like this:

• Steps to reproduce: #include <libportal/portal.h> (only) and try to call instance methods on XdpSettings (?)
• Expected result: can do so
• Actual result: compiler errors because settings.h wasn't included

[TheEvilSkeleton]

It sounds like you're implicitly reporting a bug. What is the bug? It's usually better to describe the bug than making maintainers reverse-engineer it from a proposed fix, particularly in projects that are limited by maintainer bandwidth.

True, sorry

[TheEvilSkeleton]

• Steps to reproduce: #include <libportal/portal.h> (only) and try to call instance methods on XdpSettings (?)

• Expected result: can do so

• Actual result: compiler errors because settings.h wasn't included

Yes, it's pretty much that. I also wrote a reproducer in this commit: TheEvilSkeleton/Settings-Not-Included@8eb0714

[smcv]

OK, thanks for the reproducer. I think that confirms my belief that a better fix for this would be to add #include <libportal/settings.h> to portal.h so that you don't have to know about the individual headers.

Are there any other public headers that are not included in portal.h? We should add those too, unless there's a reason they're inappropriate (for example the GTK and Qt headers, which have extra dependencies, and are mutually exclusive between major versions of the same library).

[TheEvilSkeleton]

Are there any other public headers that are not included in portal.h? We

Not that I'm aware of, no