Minor doc fixes

diff --git a/docs/man/PolicyKit-1.xml b/docs/man/PolicyKit-1.xml
index e3a802f..6b630db 100644 (file)
--- a/docs/man/PolicyKit-1.xml
+++ b/docs/man/PolicyKit-1.xml
@@ -136,9 +136,9 @@ System Context         |                        |
       authenticating as the user) or an administrative user (by
       authenticating as a administrator). In order to integrate well
       with the rest of the user session (e.g. match the look and
-      feel), authentication agents are meant to provided by the user
-      session that the user uses. For example, an authentication agent
-      may look like this:
+      feel), authentication agents are meant to be provided by the
+      user session that the user uses. For example, an authentication
+      agent may look like this:
     </para>
     <mediaobject>
       <imageobject>

diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index f3ebca9..57544d7 100644 (file)
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -11,9 +11,9 @@
     <para>
       PolicyKit provides an authorization API intended to be used by
       privileged programs (<quote>MECHANISMS</quote>) offering service
-      to unprivileged programs (<quote>CLIENTS</quote>). See
-      <link linkend="PolicyKit-1.8">this page</link> for the system
-      architecture and big picture.
+      to unprivileged programs (<quote>CLIENTS</quote>). See the
+      <link linkend="PolicyKit-1.8">PolicyKit-1</link> manual page for
+      the system architecture and big picture.
     </para>
   </chapter>
 
@@ -25,8 +25,8 @@
       <emphasis>mechanism</emphasis> use either
       the <link linkend="ref-api">GObject API</link>,
       the <link linkend="ref-dbus-api">D-Bus API</link> or
-      the <link linkend="pkcheck.1">pkcheck</link> command to speak
-      to the PolicyKit Authority.
+      the <link linkend="pkcheck.1">pkcheck</link> command to
+      communicate with the PolicyKit Authority.
     </para>
     <para>
       Note that <emphasis>clients</emphasis> never use the PolicyKit
@@ -47,6 +47,30 @@
   </chapter>
 
   <chapter>
+    <title>Writing PolicyKit Authentication Agents</title>
+    <para>
+      Authentication agents are provided by desktop environments. When
+      an user session starts, the agent registers with the PolicyKit
+      Authority using
+      the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>
+      method. When services are needed, the authority will invoke
+      methods on
+      the <link linkend="eggdbus-interface-org.freedesktop.PolicyKit1.AuthenticationAgent">org.freedesktop.PolicyKit1.AuthenticationAgent</link>
+      D-Bus interface. Once the user is authenticated, (a privileged
+      part of) the agent invokes
+      the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse">AuthenticationAgentResponse()</link>
+      method.  Note that the PolicyKit Authority itself does not care
+      how the agent authenticates the user.
+    </para>
+    <para>
+      The <link linkend="ref-authentication-agent-api">libpolkit-agent-1</link>
+      library provides helpers to make it easy to build authentication
+      agents that use the native authentication system
+      e.g. pam<literal>(8)</literal>.
+    </para>
+  </chapter>
+
+  <chapter>
     <title>Extending PolicyKit</title>
     <para>
       PolicyKit exports a number of extension points to

diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index 7c5484a..ff5f7d7 100644 (file)
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -58,61 +58,65 @@
 
   <xi:include href="overview.xml"/>
 
-  <reference id="ref-dbus-api">
-    <title>D-Bus API Reference</title>
-    <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml"/>
-    <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthorityManager.xml"/>
-    <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml"/>
-  </reference>
+  <part id="apis">
+    <title>API Reference</title>
 
-  <reference id="ref-api">
-    <title>Core API Reference</title>
-    <xi:include href="xml/polkitauthority.xml"/>
-    <xi:include href="xml/polkitauthorizationresult.xml"/>
-    <xi:include href="xml/polkitdetails.xml"/>
-    <xi:include href="xml/polkiterror.xml"/>
-    <xi:include href="xml/polkitactiondescription.xml"/>
-    <xi:include href="xml/polkitauthoritymanager.xml"/>
-    <xi:include href="xml/polkitauthorization.xml"/>
-    <chapter id="subjects">
-      <title>Subjects</title>
-      <xi:include href="xml/polkitsubject.xml"/>
-      <xi:include href="xml/polkitunixprocess.xml"/>
-      <xi:include href="xml/polkitunixsession.xml"/>
-      <xi:include href="xml/polkitsystembusname.xml"/>
+    <chapter id="ref-dbus-api">
+      <title>D-Bus API Reference</title>
+      <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml"/>
+      <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthorityManager.xml"/>
+      <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml"/>
     </chapter>
-    <chapter id="Identities">
-      <title>Identities</title>
-      <xi:include href="xml/polkitidentity.xml"/>
-      <xi:include href="xml/polkitunixuser.xml"/>
-      <xi:include href="xml/polkitunixgroup.xml"/>
+
+    <chapter id="ref-api">
+      <title>Core API Reference</title>
+      <xi:include href="xml/polkitauthority.xml"/>
+      <xi:include href="xml/polkitauthorizationresult.xml"/>
+      <xi:include href="xml/polkitdetails.xml"/>
+      <xi:include href="xml/polkiterror.xml"/>
+      <xi:include href="xml/polkitactiondescription.xml"/>
+      <xi:include href="xml/polkitauthoritymanager.xml"/>
+      <xi:include href="xml/polkitauthorization.xml"/>
+      <chapter id="subjects">
+        <title>Subjects</title>
+        <xi:include href="xml/polkitsubject.xml"/>
+        <xi:include href="xml/polkitunixprocess.xml"/>
+        <xi:include href="xml/polkitunixsession.xml"/>
+        <xi:include href="xml/polkitsystembusname.xml"/>
+      </chapter>
+      <chapter id="Identities">
+        <title>Identities</title>
+        <xi:include href="xml/polkitidentity.xml"/>
+        <xi:include href="xml/polkitunixuser.xml"/>
+        <xi:include href="xml/polkitunixgroup.xml"/>
+      </chapter>
     </chapter>
-  </reference>
 
-  <reference id="ref-backend-api">
-    <title>Backend API Reference</title>
-    <xi:include href="xml/polkitbackendauthority.xml"/>
-    <xi:include href="xml/polkitbackendlocalauthority.xml"/>
-    <xi:include href="xml/polkitbackendactionpool.xml"/>
-    <xi:include href="xml/polkitbackendsessionmonitor.xml"/>
-    <xi:include href="xml/polkitbackendconfigsource.xml"/>
-    <xi:include href="xml/polkitbackendactionlookup.xml"/>
-  </reference>
+    <chapter id="ref-backend-api">
+      <title>Backend API Reference</title>
+      <xi:include href="xml/polkitbackendauthority.xml"/>
+      <xi:include href="xml/polkitbackendlocalauthority.xml"/>
+      <xi:include href="xml/polkitbackendactionpool.xml"/>
+      <xi:include href="xml/polkitbackendsessionmonitor.xml"/>
+      <xi:include href="xml/polkitbackendconfigsource.xml"/>
+      <xi:include href="xml/polkitbackendactionlookup.xml"/>
+    </chapter>
 
-  <reference id="ref-authentication-agent-api">
-    <title>Authentication Agent API Reference</title>
-    <xi:include href="xml/polkitagentlistener.xml"/>
-    <xi:include href="xml/polkitagentsession.xml"/>
-  </reference>
+    <chapter id="ref-authentication-agent-api">
+      <title>Authentication Agent API Reference</title>
+      <xi:include href="xml/polkitagentlistener.xml"/>
+      <xi:include href="xml/polkitagentsession.xml"/>
+    </chapter>
+  </part>
 
-  <reference id="manpages">
+  <part id="manpages">
     <title>Manual Pages</title>
     <xi:include href="../man/PolicyKit-1.xml"/>
     <xi:include href="../man/polkitd-1.xml"/>
     <xi:include href="../man/pkcheck.xml"/>
     <xi:include href="../man/pkaction.xml"/>
     <xi:include href="../man/pkexec.xml"/>
-  </reference>
+  </part>
 
   <chapter id="polkit-hierarchy">
     <title>Object Hierarchy</title>
@@ -123,8 +127,6 @@
     <title>Index</title>
   </index>
 
-  <!-- License -->
-
   <appendix id="license">
     <title>License</title>
     <para>

diff --git a/src/polkitbackend/polkitbackendactionpool.c b/src/polkitbackend/polkitbackendactionpool.c
index d3d0908..77f52c6 100644 (file)
--- a/src/polkitbackend/polkitbackendactionpool.c
+++ b/src/polkitbackend/polkitbackendactionpool.c
@@ -30,6 +30,14 @@
 
 #include "polkitbackendactionpool.h"
 
+/**
+ * SECTION:polkitbackendactionpool
+ * @title: PolkitBackendActionPool
+ * @short_description: Registered actions
+ *
+ * The #PolkitBackendActionPool class is a utility class to look up registered PolicyKit actions.
+ */
+
 typedef struct
 {
   gchar *action_id;

diff --git a/src/polkitbackend/polkitbackendconfigsource.c b/src/polkitbackend/polkitbackendconfigsource.c
index 348b3e1..a98936c 100644 (file)
--- a/src/polkitbackend/polkitbackendconfigsource.c
+++ b/src/polkitbackend/polkitbackendconfigsource.c
@@ -29,8 +29,9 @@
  * @title: PolkitBackendConfigSource
  * @short_description: Access configuration files
  *
- * The #PolkitBackendConfigSource is a utility class to read configuration data
- * from a set of prioritized key-value files in a given directory.
+ * The #PolkitBackendConfigSource class is a utility class to read
+ * configuration data from a set of prioritized key-value files in a
+ * given directory.
  */
 
 struct _PolkitBackendConfigSourcePrivate

diff --git a/src/polkitbackend/polkitbackendsessionmonitor.c b/src/polkitbackend/polkitbackendsessionmonitor.c
index 667401e..fbff1fa 100644 (file)
--- a/src/polkitbackend/polkitbackendsessionmonitor.c
+++ b/src/polkitbackend/polkitbackendsessionmonitor.c
@@ -35,7 +35,7 @@
  * @title: PolkitBackendSessionMonitor
  * @short_description: Monitor sessions
  *
- * The #PolkitBackendSessionMonitor is a utility class to track and monitor sessions.
+ * The #PolkitBackendSessionMonitor class is a utility class to track and monitor sessions.
  */
 
 struct _PolkitBackendSessionMonitor