docs: Clarify that login1 signals are not emitted for convenience objects

While this is obvious if you spend a few minutes thinking about how
D-Bus signals work (in this case, they are broadcast from a system
service, so cannot apply to a specific user/session/seat), it’s a bit
easy to overlook this while putting code together which uses the login1
D-Bus API, so it’s helpful to point this hazard out specifically in the
docs.

The signals can only be emitted on the canonical objects. The
convenience objects are useful for method calls, as the calling context
can be used to dereference ‘self’ and ‘auto’, but this can’t work for
signals.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
(cherry picked from commit 82b32b997c51e259ddf66a0ec6bd7631b0ea781d)

diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index 65618356d7ee355368494b1db626f7f8a28b36eb..fda93450b0636f2b710587319e1f7987ae264c47 100644 (file)
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -1002,6 +1002,11 @@ node /org/freedesktop/login1/seat/seat0 {
       <function>CanGraphical</function>, <function>CanTTY</function>,
       or the idle state changes, <function>PropertyChanged</function> signals are sent out to clients which
       have subscribed.</para>
+
+      <para>Signals are only emitted on objects referencing a specific seat ID, not on the
+      <literal>/org/freedesktop/login1/seat/self</literal> or
+      <literal>/org/freedesktop/login1/seat/auto</literal> convenience objects, as they can only be
+      dereferenced relative to a method caller.</para>
     </refsect2>
 
     <refsect2>
@@ -1122,6 +1127,10 @@ node /org/freedesktop/login1/user/_1000 {
 
       <para>Whenever <varname>Sessions</varname> or the idle state changes,
       <function>PropertyChanged</function> signals are sent out to clients which have subscribed.</para>
+
+      <para>Signals are only emitted on objects referencing a specific UID, not on the
+      <literal>/org/freedesktop/login1/user/self</literal> convenience object, as <varname>self</varname>
+      can only be dereferenced relative to a method caller.</para>
     </refsect2>
 
     <refsect2>
@@ -1483,6 +1492,11 @@ node /org/freedesktop/login1/session/1 {
       screen-locked/unlocked. A session manager of the session should listen to this signal and act
       accordingly. This signal is sent out as a result of the <function>Lock()</function> and
       <function>Unlock()</function> methods, respectively.</para>
+
+      <para>Signals are only emitted on objects referencing a specific session ID, not on the
+      <literal>/org/freedesktop/login1/session/self</literal> or
+      <literal>/org/freedesktop/login1/session/auto</literal> convenience objects, as they can only be
+      dereferenced relative to a method caller.</para>
     </refsect2>
 
     <refsect2>