merge: branch 'lr/api-docs'

https://bugzilla.gnome.org/show_bug.cgi?id=779934

78 files changed, 595 insertions, 132 deletions

diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am
index 12a6d52f6a..f5def7b8b8 100644
--- a/docs/api/Makefile.am
+++ b/docs/api/Makefile.am
@@ -38,8 +38,9 @@ MKTMPL_OPTIONS=
 # Extra options to supply to gtkdoc-mkhtml
 MKHTML_OPTIONS=--path="$(abs_srcdir)"
 
-# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
+# Files to be included in $(DOC_MAIN_SGML_FILE)
 content_files = \
+	$(GENERATED_FILES) \
 	dbus-org.freedesktop.NetworkManager.AccessPoint.xml \
 	dbus-org.freedesktop.NetworkManager.Connection.Active.xml \
 	dbus-org.freedesktop.NetworkManager.Device.Team.xml \
diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml
index b2fe87e99e..dd5f0e47f5 100644
--- a/docs/api/network-manager-docs.xml
+++ b/docs/api/network-manager-docs.xml
@@ -6,7 +6,11 @@
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>NetworkManager Reference Manual</title>
-    <releaseinfo>Version &version;</releaseinfo>
+    <releaseinfo>
+      for NetworkManager &version;
+      The latest version of this documentation can be found on-line at
+      <ulink url="https://developer.gnome.org/NetworkManager/stable/">https://developer.gnome.org/NetworkManager/stable/</ulink>.
+    </releaseinfo>
 
     <copyright>
       <year>2012</year>
@@ -39,79 +43,42 @@
 	</address>
       </para>
     </legalnotice>
+
+    <abstract>
+      <para>
+        This manual is the reference documentation for NetworkManager, the standard
+        Linux network management service. It is intended for system administrators and
+        integrators who need to understand the capabilities of NetworkManager, its
+        configuration options, command line tools and the D-Bus API for programmatic
+        control of the service.
+      </para>
+      <para>
+        The end users NetworkManager should instead refer to respective documentation
+        of their desktop environment of choice.
+      </para>
+      <para>
+        The application developers who prefer not to use the D-Bus API directly can use the
+        <ulink url="https://developer.gnome.org/libnm/stable/">libnm</ulink> library
+        shipped with NetworkManager or its bindings to a higher level language such as
+        Python, Ruby or Vala via GObject introspection.
+      </para>
+    </abstract>
   </bookinfo>
 
-  <chapter id="manpages">
+  <part id="manpages">
     <title>Manual Pages</title>
+    <xi:include href="../../man/NetworkManager.xml"/>
+    <xi:include href="../../man/NetworkManager.conf.xml"/>
     <xi:include href="../../man/nmcli.xml"/>
+    <xi:include href="../../man/nmcli-examples.xml"/>
     <xi:include href="../../man/nmtui.xml"/>
-    <xi:include href="../../man/nm-online.xml"/>
-    <xi:include href="../../man/NetworkManager.conf.xml"/>
     <xi:include href="../../man/nm-settings.xml"><xi:fallback /></xi:include>
     <xi:include href="../../man/nm-settings-keyfile.xml"><xi:fallback /></xi:include>
     <xi:include href="../../man/nm-settings-ifcfg-rh.xml"><xi:fallback /></xi:include>
-    <xi:include href="../../man/nmcli-examples.xml"/>
-    <xi:include href="../../man/NetworkManager.xml"/>
-  </chapter>
-
-  <chapter id="spec">
-    <title>D-Bus API Reference</title>
-
-    <para>
-      This part documents the D-Bus interface used to access the
-      NetworkManager daemon.
-    </para>
-
-    <section id="dbus-interfaces">
-      <title>Interfaces</title>
-      <!-- TODO: Split me into chapters about daemon, vpn plugins, dispatcher and the secret agent.
-                    Then describe the daemon's singletons and object hierarchy. -->
-      <xi:include href="dbus-org.freedesktop.NetworkManager.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.AgentManager.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.AccessPoint.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.PPP.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.Connection.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Connection.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Connection.Active.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Adsl.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bond.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bridge.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bluetooth.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Dummy.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wired.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Generic.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Infiniband.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.IPTunnel.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macsec.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macvlan.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Modem.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OlpcMesh.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Team.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Tun.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Veth.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vlan.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vxlan.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wireless.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.WiMax.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP4Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP6Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.IP4Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.IP6Config.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Plugin.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.SecretAgent.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Statistics.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.DnsManager.xml"/>
-    </section>
-    <section id="dbus-types">
-      <title>Types</title>
-      <xi:include href="../../libnm-core/nm-dbus-types.xml"/>
-      <xi:include href="../../libnm-core/nm-vpn-dbus-types.xml"/>
-    </section>
-  </chapter>
+    <xi:include href="../../man/nm-online.xml"/>
+  </part>
 
-  <chapter id="ref-settings">
+  <part id="ref-settings">
     <title>Network Configuration Setting Specification</title>
     <para>
       This part documents the properties and value types of each "Setting"
@@ -122,16 +89,16 @@
     </para>
     <xi:include href="settings-spec.xml">
       <xi:fallback>
-	<section>
+	<chapter>
 	  <title>Configuration Settings</title>
 	  <note><para>
 	    (NetworkManager was built without full introspection support. Setting
 	    documentation is not available.)
 	  </para></note>
-	</section>
+	</chapter>
       </xi:fallback>
     </xi:include>
-    <section id="secrets-flags">
+    <chapter id="secrets-flags">
       <title>Secret flag types</title>
       <para>
         Each secret property in a setting has an associated "flags" property
@@ -165,8 +132,141 @@
           </listitem>
         </itemizedlist>
       </para>
-    </section>
-  </chapter>
+    </chapter>
+  </part>
+
+  <part id="spec">
+    <title id="dbus-interfaces">D-Bus API Reference</title>
+
+    <para>
+      This part documents the D-Bus interface used to access the
+      NetworkManager daemon.
+    </para>
+
+    <chapter id="ref-dbus-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-agent-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager/AgentManager</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.AgentManager.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-dns-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager/DnsManager</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.DnsManager.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-settings-manager">
+      <title>The <literal>/org/freedesktop/NetworkManager/Settings</literal> object</title>
+      <!-- TODO: Describe the object here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-settings">
+      <title>The <literal>/org/freedesktop/NetworkManager/Settings/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Settings.Connection.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-devices">
+      <title>The <literal>/org/freedesktop/NetworkManager/Devices/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Statistics.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Adsl.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bond.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bridge.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Bluetooth.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Dummy.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wired.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Generic.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Infiniband.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.IPTunnel.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macsec.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macvlan.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Modem.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OlpcMesh.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Team.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Tun.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Veth.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vlan.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vxlan.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wireless.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.WiMax.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.PPP.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-active-connections">
+      <title>The <literal>/org/freedesktop/NetworkManager/ActiveConnection/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Connection.Active.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Connection.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-ip4-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/IP4Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.IP4Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-ip6-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/IP6Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.IP6Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-dhcp4-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/DHCP4Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP4Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-dhcp6-configs">
+      <title>The <literal>/org/freedesktop/NetworkManager/DHCP4Config/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.DHCP6Config.xml"/>
+    </chapter>
+
+    <chapter id="ref-dbus-access-points">
+      <title>The <literal>/org/freedesktop/NetworkManager/AccessPoint/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.AccessPoint.xml"/>
+    </chapter>
+
+    <chapter id="dbus-types">
+      <title>Types</title>
+      <xi:include href="../../libnm-core/nm-dbus-types.xml"/>
+    </chapter>
+  </part>
+
+  <part id="secret-agents">
+    <title>Secret Agent D-Bus API Reference</title>
+
+    <chapter id="dbus-secret-agent">
+      <title>Secret agents</title>
+      <!-- TODO: Describe the secret agent here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.SecretAgent.xml"/>
+    </chapter>
+  </part>
+
+  <part id="vpn-plugins">
+    <title>VPN Plugin D-Bus API Reference</title>
+
+    <chapter id="dbus-vpn-types">
+      <title>VPN services</title>
+      <!-- TODO: Describe the VPN services here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.VPN.Plugin.xml"/>
+    </chapter>
+    <chapter id="dbus-vpn-types">
+      <title>Types</title>
+      <xi:include href="../../libnm-core/nm-vpn-dbus-types.xml"/>
+    </chapter>
+  </part>
 
   <index>
     <title>Index</title>
diff --git a/docs/api/settings-spec.xsl b/docs/api/settings-spec.xsl
index 04feb3987f..80f27309d5 100644
--- a/docs/api/settings-spec.xsl
+++ b/docs/api/settings-spec.xsl
@@ -9,37 +9,58 @@
       />
 
   <xsl:template match="nm-setting-docs">
-    <section>
+    <chapter>
       <title>Configuration Settings</title>
       <xsl:apply-templates/>
-    </section>
+    </chapter>
   </xsl:template>
 
   <xsl:template match="setting">
-    <para>
-      <table>
-	<title><xsl:value-of select="@name"/> setting</title>
-	<tgroup cols="4">
-	  <thead>
-	    <row>
-              <entry>Key Name</entry>
-              <entry>Value Type</entry>
-              <entry>Default Value</entry>
-              <entry>Value Description</entry>
-	    </row>
-	  </thead>
-	  <tbody>
-	    <xsl:apply-templates/>
-	  </tbody>
-	</tgroup>
-      </table>
-    </para>
+    <refentry>
+      <xsl:attribute name="id">settings-<xsl:value-of select="@name"/></xsl:attribute>
+      <refnamediv>
+        <refname><xsl:value-of select="@name"/></refname>
+        <refpurpose><xsl:value-of select="@description"/></refpurpose>
+      </refnamediv>
+      <refsect1 role="properties">
+        <title>
+            <xsl:attribute name="id">settings-<xsl:value-of select="@name"/>.properties</xsl:attribute>
+            Properties
+        </title>
+        <para>
+          <table>
+            <tgroup cols="4">
+              <thead>
+                <row>
+                  <entry>Key Name</entry>
+                  <entry>Value Type</entry>
+                  <entry>Default Value</entry>
+                  <entry>Value Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <xsl:apply-templates/>
+              </tbody>
+            </tgroup>
+          </table>
+        </para>
+      </refsect1>
+    </refentry>
   </xsl:template>
 
   <xsl:template match="property">
     <xsl:variable name="setting_name" select="../@name"/>
     <row>
-      <entry><screen><xsl:value-of select="@name"/></screen></entry>
+      <entry><screen>
+        <xsl:value-of select="@name"/>
+        <indexterm>
+           <xsl:attribute name="zone">settings-<xsl:value-of select="../@name"/></xsl:attribute>
+           <primary>
+             <xsl:attribute name="sortas"><xsl:value-of select="@name"/></xsl:attribute>
+             <xsl:value-of select="@name"/>
+           </primary>
+        </indexterm>
+      </screen></entry>
       <entry><screen><xsl:value-of select="@type"/></screen></entry>
       <entry><screen><xsl:value-of select="@default"/></screen></entry>
       <entry><xsl:value-of select="@description"/><xsl:if test="@type = 'NMSettingSecretFlags'"> (see <xref linkend="secrets-flags"/> for flag values)</xsl:if></entry>
diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml
index 705bcfc188..b03efc33f7 100644
--- a/docs/libnm/libnm-docs.xml
+++ b/docs/libnm/libnm-docs.xml
@@ -48,24 +48,130 @@
 
   <chapter id="ref-overview">
     <title>Overview</title>
-    <para>
-      libnm maps fairly closely to the actual D-Bus API that NetworkManager
-      provides, wrapping the remote D-Bus objects as native GObjects,
-      mapping D-Bus signals and properties to GObject signals and properties,
-      and providing helpful accessor and utility functions.  However, unlike
-      the old libnm-util/libnm-glib API, the mapping to the D-Bus API is not
-      exact, and various inconveniences and historical anomolies of the D-Bus
-      API are papered over.
-    </para>
-    <para>
-      The following is a rough overview of the libnm object structure and
-      how to use the various parts of it:
-      <mediaobject  id="libnm-overview">
-        <imageobject>
-          <imagedata fileref="libnm.png" format="PNG"/>
-        </imageobject>
-      </mediaobject>
-    </para>
+    <section id="intro">
+      <title>Introduction to libnm</title>
+      <para>
+        libnm is a client library for NetworkManager, the standard Linux network
+        management service. NetworkManager supports a wide variety of network
+        configuration scenarios, hardware devices and protocol families. Most of
+        the functionality is exposed on a
+        <ulink url="https://developer.gnome.org/NetworkManager/stable/spec.html">D-Bus API</ulink>,
+        allowing other tools to use the functionality provided by NetworkManager.
+      </para>
+      <para>
+        libnm provides C language bindings for functionality provided by
+        NetworkManager, optionally useful from other language runtimes as well.
+      </para>
+      <para>
+        libnm maps fairly closely to the actual D-Bus API that NetworkManager
+        provides, wrapping the remote D-Bus objects as native GObjects,
+        mapping D-Bus signals and properties to GObject signals and properties,
+        and providing helpful accessor and utility functions.  However, unlike
+        the old libnm-util/libnm-glib API, the mapping to the D-Bus API is not
+        exact, and various inconveniences and historical anomolies of the D-Bus
+        API are papered over.
+      </para>
+      <para>
+        The following is a rough overview of the libnm object structure and
+        how to use the various parts of it:
+        <mediaobject  id="libnm-overview">
+          <imageobject>
+            <imagedata fileref="libnm.png" format="PNG"/>
+          </imageobject>
+        </mediaobject>
+      </para>
+    </section>
+
+    <section id="usage">
+      <title>Using libnm</title>
+      <simplesect>
+        <title>When to use libnm</title>
+        <para>
+          libnm is fairly simple to use from C. It's based on glib and GObject.
+          If your project uses these already you'll find integration libnm with your
+          project rather convenient. In fact, the <command>nmcli</command> tool shipped
+          with NetworkManager is based on libnm.
+        </para>
+        <para>
+          libnm should be also the way to go if your project does something non-trivial
+          with NetworkManager, such as manipulating the connection profiles.
+          That is, if you're writing a specialized networking control tool or a desktop
+          environment, libnm is probably the right choice. The popular desktop
+          environments in fact all use libnm directly or with nm-applet and
+          nm-connection-editor that are all based on libnm.
+        </para>
+        <para>
+          An alternative to use of libnm is the use of the
+          <ulink url="https://developer.gnome.org/NetworkManager/stable/spec.html">D-Bus API</ulink>
+          directly.  This gives you larger flexibility and reduces the overhead of linking
+          with the libnm library. This makes sense if your task is simple and you have a good
+          D-Bus library at your disposal. Activating a particular connection profile
+          from a Python script is a good example of a task that is perfectly simple
+          without using libnm.
+        </para>
+      </simplesect>
+
+      <simplesect>
+        <title>How to use libnm</title>
+        <para>
+          You can use the libnm's C API directly. To do so, all libnm programs need to
+          include <filename>NetworkManager.h</filename> that provides necessary definitions.
+          The rest of the API is documented in the reference manual.
+        </para>
+        <informalexample><programlisting><![CDATA[#include <glib.h>
+#include <NetworkManager.h>
+
+int
+main (int argc, char *argv[])
+{
+	NMClient *client;
+
+	client = nm_client_new (NULL, NULL);
+	if (client)
+		g_print ("NetworkManager version: %s\n", nm_client_get_version (client));
+}]]></programlisting></informalexample>
+        <para>
+          Use <command>pkg-config</command> for <varname>libnm</varname> to discover the necessary
+          compiler flags.
+        </para>
+  <screen><prompt>$ </prompt><userinput>cc $(pkg-config --libs --cflags libnm) -o hello-nm hello-nm.c</userinput>
+  <prompt>$ </prompt><userinput>./hello-nm</userinput>
+  NetworkManager version: &version;
+  <prompt>$ </prompt></screen>
+        <para>
+          Utilize the <varname>PKG_CHECK_MODULES</varname> macro to integrate with an
+          autoconf-based build system. It's also recommended to use
+          <varname>NM_VERSION_MIN_REQUIRED</varname> and <varname>NM_VERSION_MAX_ALLOWED</varname>
+          macros to tell libnm headers which API version does your application need to work with.
+          If you use them, the compiler will warn you when you use functionality that is not
+          available in the versions you specified.
+        </para>
+        <informalexample><programlisting><![CDATA[PKG_CHECK_MODULES(LIBNM, libnm >= 1.8)
+LIBNM_CFLAGS="$LIBNM_CFLAGS -DNM_VERSION_MIN_REQUIRED=NM_VERSION_1_8"
+LIBNM_CFLAGS="$LIBNM_CFLAGS -DNM_VERSION_MAX_ALLOWED=NM_VERSION_1_8"]]></programlisting></informalexample>
+        <para>
+          You can use libnm from other languages than C with the use of GObject introspection.
+          This includes Perl, Python, Javascript, Lua, Ruby and more. The example below shows what the
+          typical libnm use in Python would look like.
+        </para>
+        <informalexample><programlisting><![CDATA[import gi
+gi.require_version('NM', '1.0')
+from gi.repository import NM
+
+client = NM.Client.new(None)
+print ("NetworkManager version " + client.get_version())]]></programlisting></informalexample>
+        <para>
+          There's <ulink url="https://lazka.github.io/pgi-docs/#NM-1.0">NM-1.0 Python API Reference</ulink>
+          maintained a third party that is generated from the introspection metadata.
+        </para>
+        <para>
+          In general, the C API documentation applies to the use GObject introspection
+          from other languages, with the calling convention respecting the language's
+          customs. Consult the source tree for
+          <ulink url="https://cgit.freedesktop.org/NetworkManager/NetworkManager/tree/examples">some examples</ulink>.
+        </para>
+      </simplesect>
+    </section>
   </chapter>
 
   <chapter>
diff --git a/introspection/org.freedesktop.NetworkManager.AccessPoint.xml b/introspection/org.freedesktop.NetworkManager.AccessPoint.xml
index 617c8671b6..769ab7a935 100644
--- a/introspection/org.freedesktop.NetworkManager.AccessPoint.xml
+++ b/introspection/org.freedesktop.NetworkManager.AccessPoint.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.AccessPoint:
+      @short_description: Wi-Fi Access Point
+
+  -->
   <interface name="org.freedesktop.NetworkManager.AccessPoint">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.AgentManager.xml b/introspection/org.freedesktop.NetworkManager.AgentManager.xml
index 86b4404a1a..e8df4872af 100644
--- a/introspection/org.freedesktop.NetworkManager.AgentManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.AgentManager.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/freedesktop/NetworkManager/AgentManager">
+  <!--
+      org.freedesktop.NetworkManager.AgentManager:
+      @short_description: Secret Agent Manager
+
+  -->
   <interface name="org.freedesktop.NetworkManager.AgentManager">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Checkpoint.xml b/introspection/org.freedesktop.NetworkManager.Checkpoint.xml
index 1c5050f279..daab0c903b 100644
--- a/introspection/org.freedesktop.NetworkManager.Checkpoint.xml
+++ b/introspection/org.freedesktop.NetworkManager.Checkpoint.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Checkpoint:
+      @short_description: Configuration and State Snapshot
 
       A snapshot of NetworkManager state for a given device list
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
index 383ede34a9..3ffa4cd67a 100644
--- a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
+++ b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Connection.Active:
+      @short_description: Active Connection
 
       Objects that implement the Connection.Active interface represent an
       attempt to connect to a network using the details provided by a Connection
diff --git a/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml b/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml
index 5244bcaaa0..2e0ae82e10 100644
--- a/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.DHCP4Config:
+      @short_description: IPv4 DHCP Client State
 
       Options and configuration returned by the IPv4 DHCP server.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml b/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml
index 09e2ca8676..0f064c4c87 100644
--- a/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.DHCP6Config:
+      @short_description: IPv6 DHCP Client State
 
       Options and configuration returned by the IPv6 DHCP server.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml b/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml
index 0986f06995..ef1f580f06 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Adsl:
+      @short_description: ADSL Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Adsl">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml b/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml
index f891220d25..43a3047c1e 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Bluetooth:
+      @short_description: Bluetooth Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Bluetooth">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Bond.xml b/introspection/org.freedesktop.NetworkManager.Device.Bond.xml
index e6288a1530..9ee24e8107 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Bond.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Bond.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Bond:
+      @short_description: Bonding Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Bond">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml b/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml
index a6c5710dc3..e64e400627 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Bridge:
+      @short_description: Bridging Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Bridge">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml b/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml
index 7492c061bf..0b5237f8c0 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Dummy:
+      @short_description: Dummy Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Dummy">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Generic.xml b/introspection/org.freedesktop.NetworkManager.Device.Generic.xml
index 39aafc2c1b..ecbfed6895 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Generic.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Generic.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Generic:
+      @short_description: Unrecognized Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Generic">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml b/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml
index dda71e3e67..ef92f3a992 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.IPTunnel:
+      @short_description: IP Tunneling Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.IPTunnel">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml b/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml
index 34b5fadd1f..26e2694bef 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Infiniband:
+      @short_description: Infiniband Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Infiniband">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml b/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml
index e67f937cbb..0f109c1d6c 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Macsec:
+      @short_description: MACSec Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Macsec">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml b/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml
index e0b58ba4da..3370ab04d6 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Macvlan:
+      @short_description: MAC VLAN Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Macvlan">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Modem.xml b/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
index 29eff68246..d3cbd55768 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Modem:
+      @short_description: Modem Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Modem">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml b/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml
index 3d6162f334..0e54403d8f 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.OlpcMesh:
+      @short_description: OLPC Wireless Mesh Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.OlpcMesh">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml b/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml
index 84c3b6fe47..39230b7fd0 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Statistics:
+      @short_description: Device Statistic Counters
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Statistics">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Team.xml b/introspection/org.freedesktop.NetworkManager.Device.Team.xml
index c7b50a386d..c187b511d1 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Team.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Team.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Team:
+      @short_description: Teaming Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Team">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Tun.xml b/introspection/org.freedesktop.NetworkManager.Device.Tun.xml
index 68167cc57d..9dc4661a99 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Tun.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Tun.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Tun:
+      @short_description: Userspace Tunneling Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Tun">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Veth.xml b/introspection/org.freedesktop.NetworkManager.Device.Veth.xml
index 93c7c87024..a5265e074e 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Veth.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Veth.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Veth:
+      @short_description: Virtual Ethernet Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Veth">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml b/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml
index e5bf7c44ed..75d6ba430b 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Vlan:
+      @short_description: Virtual LAN Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Vlan">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml b/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml
index 8eae63c647..52b59cc514 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Vxlan:
+      @short_description: VXLAN Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Vxlan">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml b/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml
index 844856cc19..ac2a393a0f 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.WiMax:
+      @short_description: WiMax Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.WiMax">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wired.xml b/introspection/org.freedesktop.NetworkManager.Device.Wired.xml
index 3aa4540fb5..ae709031ba 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Wired.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Wired.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Wired:
+      @short_description: Wired Ethernet Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Wired">
     <annotation name="org.gtk.GDBus.C.Name" value="DeviceEthernet"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
index 1973b417dc..bff89120a5 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device.Wireless:
+      @short_description: Wi-Fi Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device.Wireless">
     <annotation name="org.gtk.GDBus.C.Name" value="DeviceWifi"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Device.xml b/introspection/org.freedesktop.NetworkManager.Device.xml
index d4535a84da..ee424101e6 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.Device:
+      @short_description: Device
+
+  -->
   <interface name="org.freedesktop.NetworkManager.Device">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.DnsManager.xml b/introspection/org.freedesktop.NetworkManager.DnsManager.xml
index 3a0c757bdc..dd96e0f660 100644
--- a/introspection/org.freedesktop.NetworkManager.DnsManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.DnsManager.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.DnsManager:
+      @short_description: DNS Configuration State
 
       The interface contains DNS-related information.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.IP4Config.xml b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
index 17f57bc685..0b04af94e8 100644
--- a/introspection/org.freedesktop.NetworkManager.IP4Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.IP4Config:
+      @short_description: IPv4 Configuration Set
+
+  -->
   <interface name="org.freedesktop.NetworkManager.IP4Config">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.IP6Config.xml b/introspection/org.freedesktop.NetworkManager.IP6Config.xml
index e5cab7132d..d2859b5af5 100644
--- a/introspection/org.freedesktop.NetworkManager.IP6Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.IP6Config.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.IP6Config:
+      @short_description: IPv6 Configuration Set
+
+  -->
   <interface name="org.freedesktop.NetworkManager.IP6Config">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.PPP.xml b/introspection/org.freedesktop.NetworkManager.PPP.xml
index e4c6a2c869..401ee9492b 100644
--- a/introspection/org.freedesktop.NetworkManager.PPP.xml
+++ b/introspection/org.freedesktop.NetworkManager.PPP.xml
@@ -1,6 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.PPP:
+      @short_description: Helper interface for a PPP plugin
+
+  -->
   <interface name="org.freedesktop.NetworkManager.PPP">
     <annotation name="org.gtk.GDBus.C.Name" value="PPP_Manager"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.SecretAgent.xml b/introspection/org.freedesktop.NetworkManager.SecretAgent.xml
index 33296fb06f..654b3f2f05 100644
--- a/introspection/org.freedesktop.NetworkManager.SecretAgent.xml
+++ b/introspection/org.freedesktop.NetworkManager.SecretAgent.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.SecretAgent:
+      @short_description: User Secret Agent
 
       Private D-Bus interface used by secret agents that store and provide
       secrets to NetworkManager. If an agent provides secrets to NetworkManager
diff --git a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
index cf33120ce8..61bd26ddc6 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Settings.Connection:
+      @short_description: Connection Settings Profile
 
       Represents a single network connection configuration.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.Settings.xml b/introspection/org.freedesktop.NetworkManager.Settings.xml
index 32675e02d8..61940f912a 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Settings:
+      @short_description: Connection Settings Profile Manager
 
       The Settings interface allows clients to view and administrate the
       connections stored and used by NetworkManager.
diff --git a/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml b/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml
index 897cea0b0a..5d57908665 100644
--- a/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml
+++ b/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.VPN.Connection:
+      @short_description: Active VPN Connection
 
       Represents an active connection to a Virtual Private Network.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml b/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml
index 7eed97210f..0c68f76e28 100644
--- a/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml
+++ b/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml
@@ -3,6 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.VPN.Plugin:
+      @short_description: VPN Service
 
       This interface is provided by plugins providing VPN services to the
       NetworkManager daemon.
diff --git a/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml b/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml
index a766927943..1028afc0cf 100644
--- a/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml
+++ b/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/">
+  <!--
+      org.freedesktop.NetworkManager.WiMax.Nsp:
+      @short_description: WiMax Network Service Provider
+
+  -->
   <interface name="org.freedesktop.NetworkManager.WiMax.Nsp">
 
     <!--
diff --git a/introspection/org.freedesktop.NetworkManager.xml b/introspection/org.freedesktop.NetworkManager.xml
index 0899d382a2..ebd04a898b 100644
--- a/introspection/org.freedesktop.NetworkManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/freedesktop/NetworkManager">
+  <!--
+      org.freedesktop.NetworkManager:
+      @short_description: Connection Manager
+
+  -->
   <interface name="org.freedesktop.NetworkManager">
     <annotation name="org.gtk.GDBus.C.Name" value="Manager"/>
 
diff --git a/libnm-core/nm-setting-8021x.h b/libnm-core/nm-setting-8021x.h
index ac38d94e98..0f5f7ddd9e 100644
--- a/libnm-core/nm-setting-8021x.h
+++ b/libnm-core/nm-setting-8021x.h
@@ -76,7 +76,7 @@ typedef enum { /*< underscore_name=nm_setting_802_1x_ck_scheme >*/
 } NMSetting8021xCKScheme;
 
 /**
- * NMSetting8021xAuthFlags
+ * NMSetting8021xAuthFlags:
  * @NM_SETTING_802_1X_AUTH_FLAGS_NONE: No flags
  * @NM_SETTING_802_1X_AUTH_FLAGS_TLS_1_0_DISABLE: Disable TLSv1.0
  * @NM_SETTING_802_1X_AUTH_FLAGS_TLS_1_1_DISABLE: Disable TLSv1.1
@@ -174,6 +174,8 @@ typedef enum { /*< underscore_name=nm_setting_802_1x_auth_flags >*/
 
 /**
  * NMSetting8021x:
+ *
+ * AIEEE 802.1x Authentication Settings
  */
 struct _NMSetting8021x {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-adsl.h b/libnm-core/nm-setting-adsl.h
index d1f975e962..4f04355ec8 100644
--- a/libnm-core/nm-setting-adsl.h
+++ b/libnm-core/nm-setting-adsl.h
@@ -56,6 +56,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingAdsl:
+ *
+ * ADSL Settings
  */
 struct _NMSettingAdsl {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-bluetooth.h b/libnm-core/nm-setting-bluetooth.h
index 6746782e7c..312aab1440 100644
--- a/libnm-core/nm-setting-bluetooth.h
+++ b/libnm-core/nm-setting-bluetooth.h
@@ -61,6 +61,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingBluetooth:
+ *
+ * Bluetooth Settings
  */
 struct _NMSettingBluetooth {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-bond.h b/libnm-core/nm-setting-bond.h
index ee2da97778..e2d8f9b562 100644
--- a/libnm-core/nm-setting-bond.h
+++ b/libnm-core/nm-setting-bond.h
@@ -72,6 +72,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingBond:
+ *
+ * Bonding Settings
  */
 struct _NMSettingBond {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-bridge-port.h b/libnm-core/nm-setting-bridge-port.h
index 690f9d0df9..0ff6d9f13b 100644
--- a/libnm-core/nm-setting-bridge-port.h
+++ b/libnm-core/nm-setting-bridge-port.h
@@ -45,6 +45,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingBridgePort:
+ *
+ * Bridge Port Settings
  */
 struct _NMSettingBridgePort {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-bridge.h b/libnm-core/nm-setting-bridge.h
index 918b9c16c8..81e4c64424 100644
--- a/libnm-core/nm-setting-bridge.h
+++ b/libnm-core/nm-setting-bridge.h
@@ -50,6 +50,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingBridge:
+ *
+ * Bridging Settings
  */
 struct _NMSettingBridge {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-cdma.h b/libnm-core/nm-setting-cdma.h
index 85ad3e4c86..6e429bd122 100644
--- a/libnm-core/nm-setting-cdma.h
+++ b/libnm-core/nm-setting-cdma.h
@@ -48,6 +48,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingCdma:
+ *
+ * CDMA-based Mobile Broadband Settings
  */
 struct _NMSettingCdma {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-connection.h b/libnm-core/nm-setting-connection.h
index 89fa64ce6d..bd5b98ff4a 100644
--- a/libnm-core/nm-setting-connection.h
+++ b/libnm-core/nm-setting-connection.h
@@ -99,8 +99,7 @@ typedef enum {
 /**
  * NMSettingConnection:
  *
- * The NMSettingConnection struct contains only private data.
- * It should only be accessed through the functions described below.
+ * General Connection Profile Settings
  */
 struct _NMSettingConnection {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-dcb.h b/libnm-core/nm-setting-dcb.h
index 4a3c7329d1..d2a364a224 100644
--- a/libnm-core/nm-setting-dcb.h
+++ b/libnm-core/nm-setting-dcb.h
@@ -94,6 +94,8 @@ typedef enum { /*< flags >*/
 
 /**
  * NMSettingDcb:
+ *
+ * Data Center Bridging Settings
  */
 struct _NMSettingDcb {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-dummy.h b/libnm-core/nm-setting-dummy.h
index fdeb76059f..62fe3fa67a 100644
--- a/libnm-core/nm-setting-dummy.h
+++ b/libnm-core/nm-setting-dummy.h
@@ -41,6 +41,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingDummy:
+ *
+ * Dummy Link Settings
  */
 struct _NMSettingDummy {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-generic.h b/libnm-core/nm-setting-generic.h
index a5e94f6251..864b900494 100644
--- a/libnm-core/nm-setting-generic.h
+++ b/libnm-core/nm-setting-generic.h
@@ -41,6 +41,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingGeneric:
+ *
+ * Generic Link Settings
  */
 struct _NMSettingGeneric {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-gsm.h b/libnm-core/nm-setting-gsm.h
index 8dd4793efa..8516698dbd 100644
--- a/libnm-core/nm-setting-gsm.h
+++ b/libnm-core/nm-setting-gsm.h
@@ -56,6 +56,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingGsm:
+ *
+ * GSM-based Mobile Broadband Settings
  */
 struct _NMSettingGsm {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-infiniband.h b/libnm-core/nm-setting-infiniband.h
index 30e1158fe1..ff78b3dce5 100644
--- a/libnm-core/nm-setting-infiniband.h
+++ b/libnm-core/nm-setting-infiniband.h
@@ -47,6 +47,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingInfiniband:
+ *
+ * Infiniband Settings
  */
 struct _NMSettingInfiniband {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-ip-tunnel.h b/libnm-core/nm-setting-ip-tunnel.h
index 081b171b04..dfa6211685 100644
--- a/libnm-core/nm-setting-ip-tunnel.h
+++ b/libnm-core/nm-setting-ip-tunnel.h
@@ -53,6 +53,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingIPTunnel:
+ *
+ * IP Tunneling Settings
  */
 struct _NMSettingIPTunnel {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-ip4-config.h b/libnm-core/nm-setting-ip4-config.h
index adef375464..ca89450937 100644
--- a/libnm-core/nm-setting-ip4-config.h
+++ b/libnm-core/nm-setting-ip4-config.h
@@ -89,6 +89,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingIP4Config:
+ *
+ * IPv4 Settings
  */
 struct _NMSettingIP4Config {
 	NMSettingIPConfig parent;
diff --git a/libnm-core/nm-setting-ip6-config.h b/libnm-core/nm-setting-ip6-config.h
index 8e2c7771d1..e01a36b756 100644
--- a/libnm-core/nm-setting-ip6-config.h
+++ b/libnm-core/nm-setting-ip6-config.h
@@ -139,6 +139,8 @@ typedef enum {
 
 /**
  * NMSettingIP6Config:
+ *
+ * IPv6 Settings
  */
 struct _NMSettingIP6Config {
 	NMSettingIPConfig parent;
diff --git a/libnm-core/nm-setting-macsec.h b/libnm-core/nm-setting-macsec.h
index f9431dfe51..6a524faabf 100644
--- a/libnm-core/nm-setting-macsec.h
+++ b/libnm-core/nm-setting-macsec.h
@@ -50,6 +50,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingMacsec:
+ *
+ * MACSec Settings
  */
 struct _NMSettingMacsec {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-macvlan.h b/libnm-core/nm-setting-macvlan.h
index 33860aacc2..605efd0f9e 100644
--- a/libnm-core/nm-setting-macvlan.h
+++ b/libnm-core/nm-setting-macvlan.h
@@ -46,6 +46,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingMacvlan:
+ *
+ * MAC VLAN Settings
  */
 struct _NMSettingMacvlan {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-olpc-mesh.h b/libnm-core/nm-setting-olpc-mesh.h
index 162373b3e4..69b3c6e96e 100644
--- a/libnm-core/nm-setting-olpc-mesh.h
+++ b/libnm-core/nm-setting-olpc-mesh.h
@@ -46,6 +46,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingOlpcMesh:
+ *
+ * OLPC Wireless Mesh Settings
  */
 struct _NMSettingOlpcMesh {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-ppp.h b/libnm-core/nm-setting-ppp.h
index 39b578b35e..01536d84c7 100644
--- a/libnm-core/nm-setting-ppp.h
+++ b/libnm-core/nm-setting-ppp.h
@@ -61,6 +61,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingPpp:
+ *
+ * Point-to-Point Protocol Settings
  */
 struct _NMSettingPpp {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-pppoe.h b/libnm-core/nm-setting-pppoe.h
index 56d42efd3b..b6717cde81 100644
--- a/libnm-core/nm-setting-pppoe.h
+++ b/libnm-core/nm-setting-pppoe.h
@@ -47,6 +47,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingPppoe:
+ *
+ * PPP-over-Ethernet Settings
  */
 struct _NMSettingPppoe {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-proxy.h b/libnm-core/nm-setting-proxy.h
index e80789b4ac..0c72799f80 100644
--- a/libnm-core/nm-setting-proxy.h
+++ b/libnm-core/nm-setting-proxy.h
@@ -58,6 +58,11 @@ typedef enum {
 #define NM_SETTING_PROXY_PAC_URL "pac-url"
 #define NM_SETTING_PROXY_PAC_SCRIPT "pac-script"
 
+/**
+ * NMSettingProxy:
+ *
+ * WWW Proxy Settings
+ */
 struct _NMSettingProxy {
 	NMSetting parent;
 };
diff --git a/libnm-core/nm-setting-serial.h b/libnm-core/nm-setting-serial.h
index 16cad3fae2..2362b2463e 100644
--- a/libnm-core/nm-setting-serial.h
+++ b/libnm-core/nm-setting-serial.h
@@ -62,6 +62,8 @@ typedef enum {
 
 /**
  * NMSettingSerial:
+ *
+ * Serial Link Settings
  */
 struct _NMSettingSerial {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-team-port.h b/libnm-core/nm-setting-team-port.h
index 3b9dc09e2f..4fcc51083a 100644
--- a/libnm-core/nm-setting-team-port.h
+++ b/libnm-core/nm-setting-team-port.h
@@ -42,6 +42,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingTeamPort:
+ *
+ * Team Port Settings
  */
 struct _NMSettingTeamPort {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-team.h b/libnm-core/nm-setting-team.h
index baaa073d4c..532963aacb 100644
--- a/libnm-core/nm-setting-team.h
+++ b/libnm-core/nm-setting-team.h
@@ -42,6 +42,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingTeam:
+ *
+ * Teaming Settings
  */
 struct _NMSettingTeam {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-tun.h b/libnm-core/nm-setting-tun.h
index 63c0cbd8cb..d977e381fa 100644
--- a/libnm-core/nm-setting-tun.h
+++ b/libnm-core/nm-setting-tun.h
@@ -62,6 +62,8 @@ typedef enum {
 
 /**
  * NMSettingTun:
+ *
+ * Tunnel Settings
  */
 struct _NMSettingTun {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-vlan.h b/libnm-core/nm-setting-vlan.h
index b147a18574..ec41b59504 100644
--- a/libnm-core/nm-setting-vlan.h
+++ b/libnm-core/nm-setting-vlan.h
@@ -48,6 +48,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingVlan:
+ *
+ * VLAN Settings
  */
 struct _NMSettingVlan {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-vpn.h b/libnm-core/nm-setting-vpn.h
index 79f3d642b7..115aa8676e 100644
--- a/libnm-core/nm-setting-vpn.h
+++ b/libnm-core/nm-setting-vpn.h
@@ -49,6 +49,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingVpn:
+ *
+ * VPN Settings
  */
 struct _NMSettingVpn {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-vxlan.h b/libnm-core/nm-setting-vxlan.h
index fab2d8201d..ce26694119 100644
--- a/libnm-core/nm-setting-vxlan.h
+++ b/libnm-core/nm-setting-vxlan.h
@@ -58,6 +58,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingVxlan:
+ *
+ * VXLAN Settings
  */
 struct _NMSettingVxlan {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-wimax.h b/libnm-core/nm-setting-wimax.h
index b9c86f3ace..fb0abbac9f 100644
--- a/libnm-core/nm-setting-wimax.h
+++ b/libnm-core/nm-setting-wimax.h
@@ -44,6 +44,8 @@ G_BEGIN_DECLS
 
 /**
  * NMSettingWimax:
+ *
+ * WiMax Settings
  */
 struct _NMSettingWimax {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-wired.h b/libnm-core/nm-setting-wired.h
index 0978ae90fc..015f09da3f 100644
--- a/libnm-core/nm-setting-wired.h
+++ b/libnm-core/nm-setting-wired.h
@@ -96,6 +96,8 @@ typedef enum { /*< flags >*/
 
 /**
  * NMSettingWired:
+ *
+ * Wired Ethernet Settings
  */
 struct _NMSettingWired {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-wireless-security.h b/libnm-core/nm-setting-wireless-security.h
index 290d4f265f..ae252f1124 100644
--- a/libnm-core/nm-setting-wireless-security.h
+++ b/libnm-core/nm-setting-wireless-security.h
@@ -91,6 +91,8 @@ typedef enum {
 
 /**
  * NMSettingWirelessSecurity:
+ *
+ * Wi-Fi Security Settings
  */
 struct _NMSettingWirelessSecurity {
 	NMSetting parent;
diff --git a/libnm-core/nm-setting-wireless.h b/libnm-core/nm-setting-wireless.h
index 1d58903fc1..b0ef475682 100644
--- a/libnm-core/nm-setting-wireless.h
+++ b/libnm-core/nm-setting-wireless.h
@@ -101,6 +101,8 @@ typedef enum {
 
 /**
  * NMSettingWireless:
+ *
+ * Wi-Fi Settings
  */
 struct _NMSettingWireless {
 	NMSetting parent;
diff --git a/libnm/generate-setting-docs.py b/libnm/generate-setting-docs.py
index e1ea9723dc..86fe08cde1 100755
--- a/libnm/generate-setting-docs.py
+++ b/libnm/generate-setting-docs.py
@@ -112,7 +112,7 @@ def get_prop_type(setting, pspec, propxml):
 
     return prop_type
 
-def get_docs(setting, pspec, propxml):
+def get_docs(propxml):
     doc_xml = propxml.find('gi:doc', ns_map)
     if doc_xml is None:
         return None
@@ -162,6 +162,14 @@ def get_default_value(setting, pspec, propxml):
 
     return default_value
 
+def cmp_settings(x,y):
+    x_prefix = x.attrib['{%s}symbol-prefix' % ns_map['c']]
+    y_prefix = y.attrib['{%s}symbol-prefix' % ns_map['c']]
+    if x_prefix == "setting_connection":
+        # Always sort NMSettingConnection first
+        return -1;
+    return cmp(x_prefix, y_prefix)
+
 def escape(val):
     return str(val).replace('"', '&quot;')
 
@@ -186,7 +194,7 @@ settings = girxml.findall('./gi:namespace/gi:class[@parent="Setting"]', ns_map)
 # Hack. Need a better way to do this
 ipxml = girxml.find('./gi:namespace/gi:class[@name="SettingIPConfig"]', ns_map)
 settings.extend(girxml.findall('./gi:namespace/gi:class[@parent="SettingIPConfig"]', ns_map))
-settings = sorted(settings, key=lambda setting: setting.attrib['{%s}symbol-prefix' % ns_map['c']])
+settings = sorted(settings, cmp=cmp_settings)
 
 init_constants(girxml, settings)
 
@@ -207,7 +215,10 @@ for settingxml in settings:
     new_func = NM.__getattr__(settingxml.attrib['name'])
     setting = new_func()
 
-    outfile.write("  <setting name=\"%s\">\n" % setting.props.name)
+    class_desc = get_docs(settingxml)
+    if class_desc is None:
+        raise Exception("%s needs a gtk-doc block with one-line description" % setting.props.name)
+    outfile.write("  <setting name=\"%s\" description=\"%s\">\n" % (setting.props.name, class_desc))
 
     setting_properties = { prop.name: prop for prop in GObject.list_properties(setting) }
     if args.overrides is None:
@@ -231,7 +242,7 @@ for settingxml in settings:
                 propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
 
             value_type = get_prop_type(setting, pspec, propxml)
-            value_desc = get_docs(setting, pspec, propxml)
+            value_desc = get_docs(propxml)
             default_value = get_default_value(setting, pspec, propxml)
 
         if prop in setting_overrides:
diff --git a/man/nm-settings.xsl b/man/nm-settings.xsl
index 733d08aa62..36fb82885f 100644
--- a/man/nm-settings.xsl
+++ b/man/nm-settings.xsl
@@ -126,22 +126,25 @@
   </xsl:template>
 
   <xsl:template match="setting">
-    <table>
+    <refsect2>
       <title><xsl:value-of select="@name"/> setting</title>
-      <tgroup cols="4">
-        <thead>
-          <row>
-            <entry>Key Name</entry>
-            <entry>Value Type</entry>
-            <entry>Default Value</entry>
-            <entry>Value Description</entry>
-          </row>
-        </thead>
-        <tbody>
-          <xsl:apply-templates/>
-        </tbody>
-      </tgroup>
-    </table>
+      <para><xsl:value-of select="@description"/>.</para>
+      <informaltable>
+        <tgroup cols="4">
+          <thead>
+            <row>
+              <entry>Key Name</entry>
+              <entry>Value Type</entry>
+              <entry>Default Value</entry>
+              <entry>Value Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <xsl:apply-templates/>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </refsect2>
   </xsl:template>
 
   <xsl:template match="property">