From: Simon McVittie <smcv@collabora.com>
Date: Wed, 25 Sep 2024 17:00:09 +0000 (+0100)
Subject: spec: Document the o.fd.DBus.Verbose interface
X-Git-Tag: dbus-1.15.12~15^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f8b95130502274bc10a05c13df364dfc8e344f27;p=thirdparty%2Fdbus.git

spec: Document the o.fd.DBus.Verbose interface

Like Debug.Stats, this was implemented but never documented. Do so now.

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

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index a494cdf0d..f278c1e48 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -7900,6 +7900,47 @@
 
     </sect2>
 
+    <sect2 id="message-bus-verbose-interface">
+      <title>Verbose Interface: <literal>org.freedesktop.DBus.Verbose</literal></title>
+      <para>
+        The special message bus name <literal>org.freedesktop.DBus</literal>
+        may optionally implement the
+        <literal>org.freedesktop.DBus.Verbose</literal> interface on
+        the object path <literal>/org/freedesktop/DBus</literal>.
+        In the reference implementation, this interface is an optional
+        feature, which can be enabled or disabled at compile-time.
+        On the well-known system bus or other buses that serve more than
+        one user, access to this interface should normally be restricted to
+        administrative users, but can be opened up to developers via
+        configuration if required.
+      </para>
+
+      <sect3 id="bus-messages-enable-verbose">
+        <title>Method: <literal>org.freedesktop.DBus.Verbose.EnableVerbose</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            EnableVerbose ()
+          </programlisting>
+          Start producing verbose debugging messages in an
+          implementation-specific way.
+          For example, these messages might go to standard error or to a
+          system event log.
+       </para>
+      </sect3>
+
+      <sect3 id="bus-messages-disable-verbose">
+        <title>Method: <literal>org.freedesktop.DBus.Verbose.DisableVerbose</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            DisableVerbose ()
+          </programlisting>
+          Stop producing verbose debugging messages.
+       </para>
+      </sect3>
+
+    </sect2>
   </sect1>
 <!--
   <appendix id="implementation-notes">