docs: improved DBus interface documentation

3 files changed, 213 insertions, 92 deletions

diff --git a/docs/reference/api/Makefile.am b/docs/reference/api/Makefile.am
index 413bc63b..69c11548 100644
--- a/docs/reference/api/Makefile.am
+++ b/docs/reference/api/Makefile.am
@@ -45,6 +45,7 @@ content_files = \
 
 expand_content_files = \
 	mm-overview.xml \
+	mm-dbus-reference.xml \
 	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml \
 	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml \
 	$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml \
@@ -72,6 +73,7 @@ endif
 
 EXTRA_DIST += \
 	mm-overview.xml \
+	mm-dbus-reference.xml \
 	version.xml.in \
 	$(NULL)
 
diff --git a/docs/reference/api/mm-dbus-reference.xml b/docs/reference/api/mm-dbus-reference.xml
new file mode 100644
index 00000000..3979731b
--- /dev/null
+++ b/docs/reference/api/mm-dbus-reference.xml
@@ -0,0 +1,179 @@
+<?xml version="1.0"?>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<part id="ref-dbus" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <title>D-Bus Reference</title>
+
+  <chapter id="ref-dbus-bus-name">
+    <title>The <literal>org.freedesktop.ModemManager1</literal> bus name</title>
+    <para>
+      The D-Bus name <literal>org.freedesktop.ModemManager1</literal>
+      on the system bus is used by the ModemManager daemon.
+    </para>
+    <para>
+      If this daemon isn't running, it will be started if D-Bus messages are
+      sent to the name.
+    </para>
+  </chapter>
+
+  <chapter id="ref-dbus-standard-interfaces">
+    <title>Standard interfaces</title>
+    <para>
+      Please refer to the
+      <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">
+        DBus specification at <literal>freedesktop.org</literal>
+      </ulink> for more information on how to use these standard interfaces.
+    </para>
+    <section id="ref-dbus-standard-interfaces-properties">
+      <title>org.freedesktop.DBus.Properties</title>
+      <para>
+        All objects (<link linkend="ref-dbus-object-manager">Manager</link>,
+        <link linkend="ref-dbus-object-modem">Modems</link>,
+        <link linkend="ref-dbus-object-bearer">Bearers</link>,
+        <link linkend="ref-dbus-object-sim">SIMs</link>,
+        <link linkend="ref-dbus-object-sms">SMSs</link>) exported at the
+        <link linkend="ref-dbus-bus-name"><literal>org.freedesktop.ModemManager1</literal></link>
+        bus name implement the standard
+        <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">
+          <literal>org.freedesktop.DBus.Properties</literal>
+        </ulink> interface. Objects implementing this interface provide a
+        common way to query for property values and also a generic signal to
+        get notified about changes in those properties.
+      </para>
+    </section>
+    <section id="ref-dbus-standard-interfaces-introspectables">
+      <title>org.freedesktop.DBus.Introspectable</title>
+      <para>
+        All objects (<link linkend="ref-dbus-object-manager">Manager</link>,
+        <link linkend="ref-dbus-object-modem">Modems</link>,
+        <link linkend="ref-dbus-object-bearer">Bearers</link>,
+        <link linkend="ref-dbus-object-sim">SIMs</link>,
+        <link linkend="ref-dbus-object-sms">SMSs</link>) exported at the
+        <link linkend="ref-dbus-bus-name"><literal>org.freedesktop.ModemManager1</literal></link>
+        bus name implement the standard
+        <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-introspectable">
+          <literal>org.freedesktop.DBus.Introspectable</literal>
+        </ulink> interface. Objects implementing this interface will provide an
+        XML-based description of the object and its interfaces.
+      </para>
+    </section>
+    <section id="ref-dbus-standard-interfaces-objectmanager">
+      <title>org.freedesktop.DBus.ObjectManager</title>
+      <para>
+        The <link linkend="ref-dbus-object-manager">Manager</link> object
+        exported at the
+        <link linkend="ref-dbus-bus-name"><literal>org.freedesktop.ModemManager1</literal></link>
+        bus name implements the standard
+        <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">
+          <literal>org.freedesktop.DBus.ObjectManager</literal>
+        </ulink> interface. This interface, included in rev. 0.17 of the DBus
+        specification, allows a generic way to control the addition and removal
+        of Modem objects, as well as the addition and removal of interfaces in
+        the given objects.
+      </para>
+    </section>
+  </chapter>
+
+  <chapter id="ref-dbus-common-types">
+    <title>Common types</title>
+    <xi:include href="mm-enums.xml"/>
+    <xi:include href="mm-errors.xml"/>
+  </chapter>
+
+  <chapter id="ref-dbus-object-manager">
+    <title>The <literal>/org/freedesktop/ModemManager1</literal> object</title>
+    <para>
+      The ModemManager process will export an object at the well-known
+      path <literal>/org/freedesktop/ModemManager1</literal>.
+    </para>
+    <para>
+      This object, which implements the standard
+      <link linkend="ref-dbus-standard-interfaces-objectmanager"><literal>org.freedesktop.DBus.ObjectManager</literal></link>, is responsible for managing the list of
+      <link linkend="ref-dbus-object-modem">Modem</link> objects.
+    </para>
+    <para>
+      This object also controls any process-wide operation, such as the log
+      level being used by the daemon.
+    </para>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml"/>
+  </chapter>
+
+  <chapter id="ref-dbus-object-modem">
+    <title>The <literal>/org/freedesktop/ModemManager/Modems</literal> objects</title>
+    <para>
+      Modem objects are exported in DBus with the following path base:
+      <literal>/org/freedesktop/ModemManager1/Modems/#</literal>, where
+      <literal>#</literal> indicates a unique unsigned integer which identifies
+      the object.
+    </para>
+    <para>
+      The Modem objects will export a generic
+      <link linkend="gdbus-org.freedesktop.ModemManager1.Modem">Modem interface</link>
+      which includes common features and actions applicable to most modem types.
+      This interface, among other actions, allows the management (creation,
+      listing, deletion) of
+      <link linkend="ref-dbus-object-bearer">Bearer</link> objects which can
+      then be used to request the modem to get in connected state.
+    </para>
+    <para>
+      Modem objects will also export the generic
+      <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Simple">Simple interface</link>.
+      This interface provides an easy access to the most simple and common
+      operations that may be performed with the modem, including connection and
+      disconnection. Users of the Simple interface do not need to take care of
+      getting the modem registered, and they also don't need to manage the
+      creation of bearers themselves. All the logic required to get the modem
+      connected or disconnected is handled by the Simple interface.
+    </para>
+    <para>
+      Modems with specific 3GPP and/or CDMA capabilities will export modem type
+      specific interfaces, like the
+      <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Modem3gpp">3GPP interface</link>
+      or the
+      <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.ModemCdma">CDMA interface</link>.
+    </para>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.ModemCdma.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml"/>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml"/>
+  </chapter>
+
+  <chapter id="ref-dbus-object-bearer">
+    <title>The <literal>/org/freedesktop/ModemManager/Bearers</literal> objects</title>
+    <para>
+      Bearer objects are owned and managed by specific
+      <link linkend="ref-dbus-object-modem">Modem</link> objects. A single Modem
+      may expose one or more Bearer objects, which can then be used to get the
+      modem into connected state.
+    </para>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml"/>
+  </chapter>
+
+  <chapter id="ref-dbus-object-sim">
+    <title>The <literal>/org/freedesktop/ModemManager/SIMs</literal> objects</title>
+    <para>
+      Broadband modems usually need a SIM card to operate. Each
+      <link linkend="ref-dbus-object-modem">Modem</link> object will therefore
+      expose up to one SIM object, which allows SIM-specific actions such as PIN
+      unlocking.
+    </para>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml"/>
+  </chapter>
+
+  <chapter id="ref-dbus-object-sms">
+    <title>The <literal>/org/freedesktop/ModemManager/SMSs</literal> objects</title>
+    <para>
+      Modems implementing the
+      <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Messaging">Messaging interface</link>
+      will export one SMS object for each SMS stored in the device.
+    </para>
+    <xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml"/>
+  </chapter>
+
+</part>
diff --git a/docs/reference/api/mm-docs.xml b/docs/reference/api/mm-docs.xml
index dd8c7843..be505735 100644
--- a/docs/reference/api/mm-docs.xml
+++ b/docs/reference/api/mm-docs.xml
@@ -6,33 +6,43 @@
 <book id="mm" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>ModemManager Reference Manual</title>
-    <releaseinfo>Version &version;</releaseinfo>
+    <releaseinfo>For ModemManager version &version;</releaseinfo>
+
+    <authorgroup>
+      <author>
+	    <firstname>Dan</firstname>
+	    <surname>Williams</surname>
+	    <affiliation>
+	      <address>
+	        <email>dcbw@redhat.com</email>
+	      </address>
+	    </affiliation>
+      </author>
+      <author>
+	    <firstname>Aleksander</firstname>
+	    <surname>Morgado</surname>
+	    <affiliation>
+	      <address>
+	        <email>aleksander@lanedo.com</email>
+	      </address>
+	    </affiliation>
+      </author>
+    </authorgroup>
 
-    <copyright>
-      <year>2008</year>
-      <holder>Novell, Inc.</holder>
-    </copyright>
     <copyright>
       <year>2008</year>
       <year>2009</year>
       <year>2010</year>
       <year>2011</year>
-      <holder>Red Hat, Inc.</holder>
-    </copyright>
-    <copyright>
-      <year>2011</year>
-      <holder>The Chromium OS Authors</holder>
-    </copyright>
-    <copyright>
-      <year>2011</year>
-      <holder>Google, Inc.</holder>
+      <year>2012</year>
+      <holder>The ModemManager Authors</holder>
     </copyright>
 
     <legalnotice>
       <para>
         Permission is granted to copy, distribute and/or modify this
         document under the terms of the <citetitle>GNU Free
-        Documentation License</citetitle>, Version 1.1 or any later
+        Documentation License</citetitle>, Version 1.3 or any later
         version published by the Free Software Foundation with no
         Invariant Sections, no Front-Cover Texts, and no Back-Cover
         Texts. You may obtain a copy of the <citetitle>GNU Free
@@ -41,6 +51,7 @@
         url="http://www.fsf.org">their Web site</ulink> or by writing
         to:
         <address>
+          The Free Software Foundation, Inc.
           <street>51 Franklin Street</street>, Suite 500
           <city>Boston</city>, <state>MA</state> <postcode>02110-1335</postcode>
           <country>USA</country>
@@ -49,90 +60,19 @@
     </legalnotice>
   </bookinfo>
 
+  <!-- Part 1, overview -->
   <xi:include href="xml/mm-overview.xml"/>
 
-  <part id="ref-dbus">
-    <title>D-Bus API Reference</title>
-
-    <chapter id="ref-dbus-objects-names">
-      <title>Objects &amp; Names</title>
-      <sect1 id="ref-dbus-well-known-name">
-        <title>The <literal>org.freedesktop.ModemManager1</literal> bus name</title>
-        <para>
-          The D-Bus name <literal>org.freedesktop.ModemManager1</literal>
-          on the system bus is used by the ModemManager daemon. If this daemon
-          isn't running, it will be started if D-Bus messages are sent to the
-          name.
-        </para>
-      </sect1>
-      <sect1 id="ref-dbus-well-known-object">
-        <title>
-          The <literal>/org/freedesktop/ModemManager</literal>
-          and <literal>/org/freedesktop/ModemManager/Modems</literal> objects
-        </title>
-        <para>
-          The ModemManager process will export an object at the well-known
-          path <literal>/org/freedesktop/ModemManager1</literal>. This object can
-          be used to list available modem objects, which will also be exposed
-          on paths with the folowing pattern
-          <literal>/org/freedesktop/ModemManager1/Modems/#</literal>.
-        </para>
-      </sect1>
-    </chapter>
-
-    <chapter>
-      <title>Common types</title>
-      <xi:include href="xml/mm-enums.xml"/>
-      <xi:include href="xml/mm-errors.xml"/>
-    </chapter>
-    <chapter>
-      <title>Manager interface</title>
-      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml"/>
-    </chapter>
-    <chapter>
-      <title>SIM interface</title>
-      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml"/>
-    </chapter>
-    <chapter>
-      <title>SMS interface</title>
-      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml"/>
-    </chapter>
-    <chapter>
-      <title>Bearer interface</title>
-      <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml"/>
-    </chapter>
-    <chapter>
-      <title>Modem interfaces</title>
-      <section>
-        <title>Generic</title>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml"/>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml"/>
-      </section>
-      <section>
-        <title>3GPP specific</title>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.xml"/>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd.xml"/>
-      </section>
-      <section>
-        <title>CDMA specific</title>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.ModemCdma.xml"/>
-      </section>
-      <section>
-        <title>Other</title>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml"/>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml"/>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml"/>
-        <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml"/>
-      </section>
-    </chapter>
-  </part>
+  <!-- Part 2, DBus reference -->
+  <xi:include href="xml/mm-dbus-reference.xml"/>
 
   <index>
     <title>Index</title>
   </index>
 
-  <chapter id="mm-hierarchy">
+  <!-- NOT needed in DBus API -->
+  <!--chapter id="mm-hierarchy">
     <title>Object Hierarchy</title>
       <xi:include href="xml/tree_index.sgml"/>
-  </chapter>
+  </chapter-->
 </book>