We could have a 'D-Bus specifics' section in the GApplication docs that explains some details of D-Bus use in GApplication.

Things we probably want to document:

_DBUS_APPLICATION_ID(UTF8_STRING) = "org.gtk.Test.bloatpad"
_DBUS_UNIQUE_NAME(UTF8_STRING) = ":1.120"
_DBUS_OBJECT_PATH(UTF8_STRING) = "/org/gtk/Test/bloatpad/windows/0"

What do these X properties mean ?

/org/gtk/Test/bloatpad
/org/gtk/Test/bloatpad/menus/AppMenu
/org/gtk/Test/bloatpad/menus/MenuBar
/org/gtk/Test/bloatpad/windows/0

What can I do with any of these paths ? (Answer: for the first/last is
g_dbus_action_group_get, for the middle ones is g_dbus_menu_model_get)

What does one use the application id (well-known name) for ?
What should one better use the unique name for ?

How does this look ? Doesn't cover the X properties (that would go into GtkApplication docs). Needs some text about well-known name vs unique name.

--

D-Bus implementation details

The details in this section are really only interesting for implementors of
'desktop shells'. Note that all the D-Bus interfaces mentioned in this
section are not considered stable API, and are subject to change. Use them at your own risk !

On platforms where D-Bus is used for GApplication, it claims the application id
as a well-known name on the users session bus. It exports an application object at the path that is created by converting the application id into an object path 'in the obvious way'. E.g. an appication with id

org.gtk.Test.bloatpad

will export its application object at

/org/gtk/Test/bloatpad

The object implements the org.gtk.Application interface, which is used by remote GApplication instances to implement 'activate', 'open', and 'commandline'. It also implements the org.gtk.Actions interface to export the application actions, and you can create a GDBusActionGroup to access these actions remotely by passing the object path to the constructor:

g_dbus_action_group_get (bus, "org.gtk.Test.bloatpad", "/org/gtk/Test/bloatpad")

When you use g_application_set_app_menu() or g_application_set_menubar(), GApplication also exports these menu models as objects on the bus, at the following paths (continuing the earlier example):

/org/gtk/Test/bloatpad/menus/AppMenu
/org/gtk/Test/bloatpad/menus/MenuBar

The objects implement the org.gtk.Menus interface. You can create a GDBusMenuModel to access these objects remotely by passing  the object paths to the constructor:

g_dbus_menu_model_get (bus, "org.gtk.Test.bloatpad", "/org/gtk/Test/bloatpad/menus/AppMenu");

When using GtkApplication together with GtkApplicationWindow, the window-specific actions are also exported on the bus, at paths like

/org/gtk/Test/bloatpad/windows/0

I think that this sort of documentation isn't really suitable to include in the gtk reference documentation.

Ideally, I'd like to see us uncommitted to D-Bus API for a cycle or two and then progress to a stage where we feel comfortable with standardising this stuff (possibly under the freedesktop.org banner).  Until then, I think we should maintain something that looks vaguely like what could become the standards document.  The wiki is probably a better place for that...

There you go:

https://live.gnome.org/GTK%2B/GApplication-dbus-apis

to be continued...

I'll add references to the wiki page in some appropriate places in the api docs.
Closing this.