spec: Have a sect2 per interface documented for the message bus

Previously, we arbitrarily divided o.fd.DBus into "messages"
(methods and signals), in one sect2, and Properties, in another sect2;
and for the only extended interface that is documented so far,
o.fd.DBus.Monitoring, we included its single method in the list of
o.fd.DBus methods.

This is putting too much weight on implementation details of how the
D-Bus protocol is implemented (with Properties being "less core" than
methods and signals), and not enough weight on how interfaces are
conceptually structured. It's more usual to group together all aspects
of an interface into one document or section, and the current arbitrary
separation is going to look more and more odd as we start documenting
more interfaces like Containers (dbus!449), Stats and Verbose.

Instead, repurpose the "Message Bus Messages" section to become the
documentation for the o.fd.DBus interface, and introduce a separate
section for each other interface that the message bus provides.
Each one contains a full list of methods, signals and properties (if any)
if it is specific to the message bus, or a cross-reference to a more
generic interface description if it is equally applicable to the message
bus and its clients.

Prompted by discussion on dbus!449.

Signed-off-by: Simon McVittie <smcv@collabora.com>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index c2736d3051ac90605a71bb7e46d33ba6955b5a09..134dfa2d457fb950dda56b0f34efacf31b2a5f9c 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -5858,11 +5858,12 @@
     </sect2>
 
     <sect2 id="message-bus-messages">
-      <title>Message Bus Messages</title>
+      <title>Message Bus Interface: <literal>org.freedesktop.DBus</literal></title>
       <para>
         The special message bus name <literal>org.freedesktop.DBus</literal>
         responds to a number of additional messages at the object path
-        <literal>/org/freedesktop/DBus</literal>.
+        <literal>/org/freedesktop/DBus</literal>,
+        implementing the <literal>org.freedesktop.DBus</literal> interface.
         That object path is also used when emitting signals such as
         <link linkend='bus-messages-name-owner-changed'>NameOwnerChanged</link>.
       </para>
@@ -5882,19 +5883,8 @@
         instead of relying on this.
       </para>
 
-      <para>
-        In addition to the method calls listed below, the message bus
-        should implement the standard
-        <link linkend="standard-interfaces-introspectable">Introspectable</link>,
-        <link linkend="standard-interfaces-peer">Peer</link> and
-        <link linkend="standard-interfaces-properties">Properties</link>
-        interfaces.
-        Support for the Properties and Peer interfaces was added in version
-        1.11.x of the reference implementation of the message bus.
-      </para>
-
       <sect3 id="bus-messages-hello">
-        <title><literal>org.freedesktop.DBus.Hello</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.Hello</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -5937,7 +5927,7 @@
       </sect3>
 
       <sect3 id="bus-messages-request-name">
-        <title><literal>org.freedesktop.DBus.RequestName</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.RequestName</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6175,7 +6165,7 @@
        </sect3>
 
        <sect3 id="bus-messages-release-name">
-        <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.ReleaseName</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6268,7 +6258,7 @@
        </sect3>
 
        <sect3 id="bus-messages-list-queued-owners">
-        <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6322,7 +6312,7 @@
       </sect3>
 
       <sect3 id="bus-messages-list-names">
-        <title><literal>org.freedesktop.DBus.ListNames</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.ListNames</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6353,7 +6343,7 @@
         </para>
       </sect3>
       <sect3 id="bus-messages-list-activatable-names">
-        <title><literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6384,7 +6374,7 @@
         </para>
       </sect3>
       <sect3 id="bus-messages-name-exists">
-        <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.NameHasOwner</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6435,7 +6425,7 @@
       </sect3>
 
       <sect3 id="bus-messages-name-owner-changed">
-        <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
+        <title>Signal: <literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
         <para>
           This is a signal:
           <programlisting>
@@ -6478,7 +6468,7 @@
         </para>
       </sect3>
       <sect3 id="bus-messages-name-lost">
-        <title><literal>org.freedesktop.DBus.NameLost</literal></title>
+        <title>Signal: <literal>org.freedesktop.DBus.NameLost</literal></title>
         <para>
           This is a signal:
           <programlisting>
@@ -6511,7 +6501,7 @@
       </sect3>
 
       <sect3 id="bus-messages-name-acquired">
-        <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
+        <title>Signal: <literal>org.freedesktop.DBus.NameAcquired</literal></title>
         <para>
           This is a signal:
           <programlisting>
@@ -6544,7 +6534,7 @@
       </sect3>
 
       <sect3 id="bus-messages-activatable-services-changed">
-        <title><literal>org.freedesktop.DBus.ActivatableServicesChanged</literal></title>
+        <title>Signal: <literal>org.freedesktop.DBus.ActivatableServicesChanged</literal></title>
         <para>
           This is a signal:
           <programlisting>
@@ -6570,7 +6560,7 @@
       </sect3>
 
       <sect3 id="bus-messages-start-service-by-name">
-        <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.StartServiceByName</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6671,7 +6661,7 @@
       </sect3>
 
       <sect3 id="bus-messages-update-activation-environment">
-        <title><literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6708,7 +6698,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-name-owner">
-        <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetNameOwner</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6759,7 +6749,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-connection-unix-user">
-        <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6812,7 +6802,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-connection-unix-process-id">
-        <title><literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -6865,7 +6855,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-connection-credentials">
-        <title><literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -7049,7 +7039,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-adt-audit-session-data">
-        <title><literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -7107,7 +7097,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-connection-selinux-security-context">
-        <title><literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -7166,7 +7156,7 @@
 
 
       <sect3 id="bus-messages-add-match">
-        <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.AddMatch</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -7197,7 +7187,7 @@
        </para>
       </sect3>
       <sect3 id="bus-messages-remove-match">
-        <title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.RemoveMatch</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -7229,7 +7219,7 @@
       </sect3>
 
       <sect3 id="bus-messages-get-id">
-        <title><literal>org.freedesktop.DBus.GetId</literal></title>
+        <title>Method: <literal>org.freedesktop.DBus.GetId</literal></title>
         <para>
           As a method:
           <programlisting>
@@ -7264,109 +7254,8 @@
         </para>
       </sect3>
 
-      <sect3 id="bus-messages-become-monitor">
-        <title><literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
-        <para>
-          As a method:
-          <programlisting>
-            BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
-          </programlisting>
-          Message arguments:
-          <informaltable>
-            <tgroup cols="3">
-              <thead>
-                <row>
-                  <entry>Argument</entry>
-                  <entry>Type</entry>
-                  <entry>Description</entry>
-                </row>
-              </thead>
-              <tbody>
-                <row>
-                  <entry>0</entry>
-                  <entry>ARRAY of STRING</entry>
-                  <entry>Match rules to add to the connection</entry>
-                </row>
-                <row>
-                  <entry>1</entry>
-                  <entry>UINT32</entry>
-                  <entry>Not used, must be 0</entry>
-                </row>
-              </tbody>
-            </tgroup>
-          </informaltable>
-        </para>
-
-        <para>
-          Converts the connection into a <emphasis>monitor
-            connection</emphasis> which can be used as a debugging/monitoring
-          tool. Only a user who is privileged on this
-          bus (by some implementation-specific definition) may create
-          monitor connections<footnote>
-            <para>
-              In the reference implementation,
-              the default configuration is that each user (identified by
-              numeric user ID) may monitor their own session bus,
-              and the root user (user ID zero) may monitor the
-              system bus.
-            </para>
-          </footnote>.
-       </para>
-
-       <para>
-         Monitor connections lose all their bus names, including the unique
-         connection name, and all their match rules. Sending messages on a
-         monitor connection is not allowed: applications should use a private
-         connection for monitoring.
-       </para>
-
-       <para>
-         Monitor connections may receive all messages, even messages that
-         should only have gone to some other connection ("eavesdropping").
-         The first argument is a list of match rules, which replace any
-         match rules that were previously active for this connection.
-         These match rules are always treated as if they contained the
-         special <literal>eavesdrop='true'</literal> member.
-       </para>
-
-       <para>
-         As a special case, an empty list of match rules (which would
-         otherwise match nothing, making the monitor useless) is treated
-         as a shorthand for matching all messages.
-       </para>
-
-       <para>
-         The second argument might be used for flags to influence the
-         behaviour of the monitor connection in future D-Bus versions.
-       </para>
-
-       <para>
-         Message bus implementations should attempt to minimize the
-         side-effects of monitoring — in particular, unlike ordinary
-         eavesdropping, monitoring the system bus does not require the
-         access control rules to be relaxed, which would change the set
-         of messages that can be delivered to their (non-monitor)
-         destinations. However, it is unavoidable that monitoring
-         will increase the message bus's resource consumption. In
-         edge cases where there was barely enough time or memory without
-         monitoring, this might result in message deliveries failing
-         when they would otherwise have succeeded.
-       </para>
-      </sect3>
-
-    </sect2>
-
-    <sect2 id="message-bus-properties">
-      <title>Message Bus Properties</title>
-      <para>
-        The special message bus name <literal>org.freedesktop.DBus</literal>
-        exports several properties (see
-        <xref linkend="standard-interfaces-properties"/>) on the object path
-        <literal>/org/freedesktop/DBus</literal>.
-      </para>
-
       <sect3 id="message-bus-properties-features">
-        <title><literal>org.freedesktop.DBus.Features</literal></title>
+        <title>Property: <literal>org.freedesktop.DBus.Features</literal></title>
         <para>
           As a property:
           <programlisting>
@@ -7471,7 +7360,7 @@
       </sect3>
 
       <sect3 id="message-bus-properties-interfaces">
-        <title><literal>org.freedesktop.DBus.Interfaces</literal></title>
+        <title>Property: <literal>org.freedesktop.DBus.Interfaces</literal></title>
         <para>
           As a property:
           <programlisting>
@@ -7503,6 +7392,139 @@
       </sect3>
     </sect2>
 
+    <sect2>
+      <title>Message Bus Introspection</title>
+      <para>
+        The message bus should implement the standard
+        <link linkend="standard-interfaces-introspectable">Introspectable</link>
+        interface.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Message Bus as a Peer</title>
+      <para>
+        The message bus should implement the standard
+        <link linkend="standard-interfaces-peer">Peer</link> interface.
+        Support for the Peer interface was added in version
+        1.11.x of the reference implementation of the message bus.
+      </para>
+    </sect2>
+
+    <sect2 id="message-bus-properties">
+      <title>Message Bus Properties</title>
+      <para>
+        The message bus should implement the standard
+        <link linkend="standard-interfaces-properties">Properties</link>
+        interface on the object path
+        <literal>/org/freedesktop/DBus</literal>.
+        The specific properties to be provided are documented as part of
+        their respective interfaces.
+        Support for the Properties interface was added in version
+        1.11.x of the reference implementation of the message bus.
+      </para>
+    </sect2>
+
+    <sect2 id="message-bus-monitoring-interface">
+      <title>Monitoring Interface: <literal>org.freedesktop.DBus.Monitoring</literal></title>
+      <para>
+        The special message bus name <literal>org.freedesktop.DBus</literal>
+        may optionally implement the
+        <literal>org.freedesktop.DBus.Monitoring</literal> interface on
+        the object path <literal>/org/freedesktop/DBus</literal>.
+      </para>
+
+      <sect3 id="bus-messages-become-monitor">
+        <title>Method: <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>ARRAY of STRING</entry>
+                  <entry>Match rules to add to the connection</entry>
+                </row>
+                <row>
+                  <entry>1</entry>
+                  <entry>UINT32</entry>
+                  <entry>Not used, must be 0</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+
+        <para>
+          Converts the connection into a <emphasis>monitor
+            connection</emphasis> which can be used as a debugging/monitoring
+          tool. Only a user who is privileged on this
+          bus (by some implementation-specific definition) may create
+          monitor connections<footnote>
+            <para>
+              In the reference implementation,
+              the default configuration is that each user (identified by
+              numeric user ID) may monitor their own session bus,
+              and the root user (user ID zero) may monitor the
+              system bus.
+            </para>
+          </footnote>.
+       </para>
+
+       <para>
+         Monitor connections lose all their bus names, including the unique
+         connection name, and all their match rules. Sending messages on a
+         monitor connection is not allowed: applications should use a private
+         connection for monitoring.
+       </para>
+
+       <para>
+         Monitor connections may receive all messages, even messages that
+         should only have gone to some other connection ("eavesdropping").
+         The first argument is a list of match rules, which replace any
+         match rules that were previously active for this connection.
+         These match rules are always treated as if they contained the
+         special <literal>eavesdrop='true'</literal> member.
+       </para>
+
+       <para>
+         As a special case, an empty list of match rules (which would
+         otherwise match nothing, making the monitor useless) is treated
+         as a shorthand for matching all messages.
+       </para>
+
+       <para>
+         The second argument might be used for flags to influence the
+         behaviour of the monitor connection in future D-Bus versions.
+       </para>
+
+       <para>
+         Message bus implementations should attempt to minimize the
+         side-effects of monitoring — in particular, unlike ordinary
+         eavesdropping, monitoring the system bus does not require the
+         access control rules to be relaxed, which would change the set
+         of messages that can be delivered to their (non-monitor)
+         destinations. However, it is unavoidable that monitoring
+         will increase the message bus's resource consumption. In
+         edge cases where there was barely enough time or memory without
+         monitoring, this might result in message deliveries failing
+         when they would otherwise have succeeded.
+       </para>
+      </sect3>
+    </sect2>
+
   </sect1>
 <!--
   <appendix id="implementation-notes">