update inline API docs

diff --git a/polkit-dbus/polkit-dbus.c b/polkit-dbus/polkit-dbus.c
index 7d35a0d..5abdf1d 100644 (file)
--- a/polkit-dbus/polkit-dbus.c
+++ b/polkit-dbus/polkit-dbus.c
@@ -26,8 +26,9 @@
 
 /**
  * SECTION:polkit-dbus
- * @short_description: Helper library for obtaining seat, session and
- * caller information via D-Bus and ConsoleKit.
+ * @title: Caller Determination
+ * @short_description: Obtaining seat, session and caller information
+ * via D-Bus and ConsoleKit.
  *
  * Helper library for obtaining seat, session and caller information
  * via D-Bus and ConsoleKit. This library is only useful when writing

diff --git a/polkit-grant/polkit-grant.c b/polkit-grant/polkit-grant.c
index 73ecbda..6308bc2 100644 (file)
--- a/polkit-grant/polkit-grant.c
+++ b/polkit-grant/polkit-grant.c
@@ -40,17 +40,21 @@
 
 /**
  * SECTION:polkit-grant
- * @short_description: Obtain privileges through authentication.
+ * @title: PolKitGrant
+ * @short_description: A class used for obtain privileges through
+ * authentication.
  *
  * These functions are used to obtain privileges for a user that is
- * able to successfully authenticate.
+ * able to successfully authenticate. It is only useful for people
+ * writing user interfaces that interfaces with the end user.
  **/
 
 /**
  * PolKitGrant:
  *
  * Objects of this class are used to obtain privileges for a user that
- * is able to successfully authenticate.
+ * is able to successfully authenticate. It is only useful for people
+ * writing user interfaces that interfaces with the end user.
  **/
 struct PolKitGrant
 {

diff --git a/polkit/polkit-action.c b/polkit/polkit-action.c
index 4fe93aa..3bc2c86 100644 (file)
--- a/polkit/polkit-action.c
+++ b/polkit/polkit-action.c
@@ -43,9 +43,10 @@
 
 /**
  * SECTION:polkit-action
- * @short_description: Actions.
+ * @title: Actions
+ * @short_description: Models what a caller is attempting to do.
  *
- * This class is used to represent an action. TODO: describe what a action really is.
+ * This class is used to represent a PolicyKit action.
  **/
 
 /**

diff --git a/polkit/polkit-caller.c b/polkit/polkit-caller.c
index b690445..14fe24e 100644 (file)
--- a/polkit/polkit-caller.c
+++ b/polkit/polkit-caller.c
@@ -25,9 +25,11 @@
 
 /**
  * SECTION:polkit-caller
- * @short_description: Callers on the system message bus.
+ * @title: Caller
+ * @short_description: Represents a process requesting a mechanism to do something.
  *
- * This class is used to represent a caller in another process connected to the system message bus.
+ * This class is used to represent a caller in another process that is
+ * calling into a mechanism to make the mechanism do something.
  **/
 
 #ifdef HAVE_CONFIG_H
@@ -52,7 +54,7 @@
  * PolKitCaller:
  *
  * Objects of this class are used to record information about a caller
- * on the system bus.
+ * in another process.
  **/
 struct PolKitCaller
 {

diff --git a/polkit/polkit-config.c b/polkit/polkit-config.c
index 7194386..7173670 100644 (file)
--- a/polkit/polkit-config.c
+++ b/polkit/polkit-config.c
@@ -47,7 +47,8 @@
 
 /**
  * SECTION:polkit-config
- * @short_description: Configuration file.
+ * @title: Configuration
+ * @short_description: Represents the system-wide <literal>/etc/PolicyKit/PolicyKit.conf</literal> file.
  *
  * This class is used to represent the /etc/PolicyKit/PolicyKit.conf
  * configuration file. Applications using PolicyKit should never use

diff --git a/polkit/polkit-context.c b/polkit/polkit-context.c
index 6d5bf93..a28ea49 100644 (file)
--- a/polkit/polkit-context.c
+++ b/polkit/polkit-context.c
@@ -54,7 +54,8 @@
 
 /**
  * SECTION:polkit-context
- * @short_description: Context.
+ * @title: Context
+ * @short_description: The main interface used to query PolicyKit.
  *
  * This class is used to represent the interface to PolicyKit - it is
  * used by Mechanisms that use PolicyKit for making

diff --git a/polkit/polkit-error.c b/polkit/polkit-error.c
index 0d20c69..ab08fd0 100644 (file)
--- a/polkit/polkit-error.c
+++ b/polkit/polkit-error.c
@@ -25,7 +25,8 @@
 
 /**
  * SECTION:polkit-error
- * @short_description: Error codes from PolicyKit.
+ * @title: Error reporting
+ * @short_description: Representation of recoverable errors.
  *
  * Error codes from PolicyKit.
  **/

diff --git a/polkit/polkit-policy-cache.c b/polkit/polkit-policy-cache.c
index 0fb6766..2e8c9c5 100644 (file)
--- a/polkit/polkit-policy-cache.c
+++ b/polkit/polkit-policy-cache.c
@@ -44,7 +44,8 @@
 
 /**
  * SECTION:polkit-policy-cache
- * @short_description: Class for holding all policy objects.
+ * @title: Policy Cache
+ * @short_description: Holds the actions defined on the system.
  *
  * This class is used to hold all policy objects (stemming from policy
  * files) and provide look-up functions.

diff --git a/polkit/polkit-policy-default.c b/polkit/polkit-policy-default.c
index f2e22fa..05e181f 100644 (file)
--- a/polkit/polkit-policy-default.c
+++ b/polkit/polkit-policy-default.c
@@ -43,7 +43,8 @@
 
 /**
  * SECTION:polkit-policy-default
- * @short_description: Defaults policy.
+ * @title: Defaults
+ * @short_description: Models the default policy for an action.
  *
  * This class records the default policy of an action.
  **/

diff --git a/polkit/polkit-policy-file-entry.c b/polkit/polkit-policy-file-entry.c
index 6f649c2..141de05 100644 (file)
--- a/polkit/polkit-policy-file-entry.c
+++ b/polkit/polkit-policy-file-entry.c
@@ -44,7 +44,8 @@
 
 /**
  * SECTION:polkit-policy-file-entry
- * @short_description: Policy files entries.
+ * @title: Policy File Entry
+ * @short_description: Represents a declared action in a policy file.
  *
  * This class is used to represent a entries in policy files.
  **/

diff --git a/polkit/polkit-policy-file.c b/polkit/polkit-policy-file.c
index 299ac81..3b8f794 100644 (file)
--- a/polkit/polkit-policy-file.c
+++ b/polkit/polkit-policy-file.c
@@ -47,7 +47,8 @@
 
 /**
  * SECTION:polkit-policy-file
- * @short_description: Policy files.
+ * @title: Policy Definition Files
+ * @short_description: Represents a set of declared actions.
  *
  * This class is used to represent a policy files.
  **/

diff --git a/polkit/polkit-result.c b/polkit/polkit-result.c
index 6d5d4b3..15e674e 100644 (file)
--- a/polkit/polkit-result.c
+++ b/polkit/polkit-result.c
@@ -25,7 +25,8 @@
 
 /**
  * SECTION:polkit-result
- * @short_description: Result of PolicyKit queries
+ * @title: Results
+ * @short_description: Definition of results of PolicyKit queries.
  *
  * These functions are used to manipulate PolicyKit results.
  **/

diff --git a/polkit/polkit-seat.c b/polkit/polkit-seat.c
index 507a1d4..094fca3 100644 (file)
--- a/polkit/polkit-seat.c
+++ b/polkit/polkit-seat.c
@@ -43,9 +43,10 @@
 
 /**
  * SECTION:polkit-seat
- * @short_description: Seats.
+ * @title: Seat
+ * @short_description: Represents a ConsoleKit Seat.
  *
- * This class is used to represent a seat. TODO: describe seat.
+ * This class is used to represent a seat.
  **/
 
 /**

diff --git a/polkit/polkit-session.c b/polkit/polkit-session.c
index 4a1d118..a05bb8d 100644 (file)
--- a/polkit/polkit-session.c
+++ b/polkit/polkit-session.c
@@ -43,9 +43,10 @@
 
 /**
  * SECTION:polkit-session
- * @short_description: Sessions.
+ * @title: Session
+ * @short_description: Represents a ConsoleKit Session.
  *
- * This class is used to represent a session. TODO: describe session.
+ * This class is used to represent a session.
  **/
 
 /**

diff --git a/polkit/polkit-types.h b/polkit/polkit-types.h
index c344161..dd1499f 100644 (file)
--- a/polkit/polkit-types.h
+++ b/polkit/polkit-types.h
@@ -32,9 +32,10 @@
 
 /**
  * SECTION:polkit-types
- * @short_description: Basic types.
+ * @title: Basic types
+ * @short_description: Type definitions for common primitive types.
  *
- * Typedefs for common primitive types.
+ * Type definitions for common primitive types.
  **/
 
 /**