update inline API docs

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

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
 {

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.
  **/
 
 /**

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
 {

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

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

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.
  **/

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.

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.
  **/

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.
  **/

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.
  **/

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.
  **/

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.
  **/
 
 /**

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.
  **/
 
 /**

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.
  **/
 
 /**