gdbus: Document the intended semantics of handles and fds

In the D-Bus wire protocol, the handle type (G_VARIANT_TYPE_HANDLE, h) is intended to be an index/pointer into the implementation's closest equivalent of GUnixFDList: its numeric value has no semantic meaning (in the same way that the numeric values of pointers have no semantic meaning), but a handle with value n acts as a reference to the nth fd in the fd list.

GDBus provides a fairly direct mapping from the wire protocol to the C API, which makes it technically possible to attach and use fds without ever referring to them in the message body, and some GLib-centric D-Bus APIs rely on this.

However, the other major implementations of D-Bus (libdbus and sd-bus) transparently replace file descriptors with handles when building messages, and transparently replace handles with file descriptors when parsing messages. This means they cannot implement D-Bus APIs that do not follow the conventional meaning of handles as indexes/pointers into an equivalent of GUnixFDList.

For interoperability, we should encourage D-Bus API designers to follow the convention, even though code written against GDBus doesn't strictly need to do so.

---

As mentioned in the test added in !1725 (merged), we were previously only testing the GDBus-specific idiom, and not the portable version.