Add some more API docs

13 files changed, 479 insertions, 33 deletions

diff --git a/src/polkit/polkitactiondescription.c b/src/polkit/polkitactiondescription.c
index f022114..f36b68d 100644
--- a/src/polkit/polkitactiondescription.c
+++ b/src/polkit/polkitactiondescription.c
@@ -35,9 +35,14 @@
  * @title: PolkitActionDescription
  * @short_description: Actions
  *
- * Encapsulates an action.
+ * Object used to encapsulate a registered action.
  */
 
+/**
+ * PolkitActionDescription:
+ *
+ * The #PolkitActionDescription struct should not be accessed directly.
+ */
 struct _PolkitActionDescription
 {
   GObject parent_instance;
@@ -99,48 +104,117 @@ polkit_action_description_get_real (PolkitActionDescription *action_description)
   return g_object_ref (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_action_id:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the action id for @action_description.
+ *
+ * Returns: A string owned by @action_description. Do not free.
+ */
 const gchar  *
 polkit_action_description_get_action_id (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_action_id (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_description:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the description used for @action_description.
+ *
+ * Returns: A string owned by @action_description. Do not free.
+ */
 const gchar  *
 polkit_action_description_get_description (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_description (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_message:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the message used for @action_description.
+ *
+ * Returns: A string owned by @action_description. Do not free.
+ */
 const gchar  *
 polkit_action_description_get_message (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_message (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_vendor_name:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the vendor name for @action_description, if any.
+ *
+ * Returns: %NULL if there is no vendor, otherwise a string owned by
+ * @action_description. Do not free.
+ */
 const gchar  *
 polkit_action_description_get_vendor_name (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_vendor_name (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_vendor_url:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the vendor URL for @action_description, if any.
+ *
+ * Returns: %NULL if there is no vendor URL, otherwise a string owned
+ * by @action_description. Do not free.
+ */
 const gchar  *
 polkit_action_description_get_vendor_url (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_vendor_url (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_implicit_any:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the implicit authorization for @action_description used for
+ * any subject.
+ *
+ * Returns: A value from the #PolkitImplicitAuthorization enumeration.
+ */
 PolkitImplicitAuthorization
 polkit_action_description_get_implicit_any (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_implicit_any (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_implicit_inactive:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the implicit authorization for @action_description used for
+ * subjects in inactive sessions on a local console.
+ *
+ * Returns: A value from the #PolkitImplicitAuthorization enumeration.
+ */
 PolkitImplicitAuthorization
 polkit_action_description_get_implicit_inactive (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_implicit_inactive (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_implicit_active:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the implicit authorization for @action_description used for
+ * subjects in active sessions on a local console.
+ *
+ * Returns: A value from the #PolkitImplicitAuthorization enumeration.
+ */
 PolkitImplicitAuthorization
 polkit_action_description_get_implicit_active (PolkitActionDescription *action_description)
 {
@@ -148,12 +222,31 @@ polkit_action_description_get_implicit_active (PolkitActionDescription *action_d
 }
 
 
+/**
+ * polkit_action_description_get_icon_name:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the icon name for @action_description, if any.
+ *
+ * Returns: %NULL if there is no icon for @action, otherwise the icon
+ * name owned by @action_description. Do not free.
+ */
 const gchar *
 polkit_action_description_get_icon_name (PolkitActionDescription *action_description)
 {
   return _polkit_action_description_get_icon_name (action_description->real);
 }
 
+/**
+ * polkit_action_description_get_annotation:
+ * @action_description: A #PolkitActionDescription.
+ * @key: An annotation key.
+ *
+ * Get the value of the annotation with @key.
+ *
+ * Returns: %NULL if there is no annoation with @key, otherwise the
+ * annotation value owned by @action_description. Do not free.
+ */
 const gchar *
 polkit_action_description_get_annotation (PolkitActionDescription *action_description,
                                           const gchar             *key)
@@ -179,6 +272,14 @@ collect_keys (EggDBusHashMap *hash_map,
 }
 
 
+/**
+ * polkit_action_description_get_annotation_keys:
+ * @action_description: A #PolkitActionDescription.
+ *
+ * Gets the keys of annotations defined in @action_description.
+ *
+ * Returns: The annotation keys owned by @action_description. Do not free.
+ */
 const gchar * const *
 polkit_action_description_get_annotation_keys (PolkitActionDescription *action_description)
 {
@@ -201,4 +302,3 @@ polkit_action_description_get_annotation_keys (PolkitActionDescription *action_d
  out:
   return (const gchar * const *) action_description->annotation_keys;
 }
-
diff --git a/src/polkit/polkitauthority.c b/src/polkit/polkitauthority.c
index 0ca8fd9..4bb7ecd 100644
--- a/src/polkit/polkitauthority.c
+++ b/src/polkit/polkitauthority.c
@@ -44,7 +44,8 @@
  * User sessions can register an authentication agent with the
  * authority. This is used for requests from untrusted clients where
  * system policy requires that the user needs to acknowledge (through
- * proving he is the user or the administrator) a given action.
+ * proving he is the user or the administrator) a given action. See
+ * #PolkitAgentListener and #PolkitAgentSession for details.
  */
 
 /**
diff --git a/src/polkit/polkitauthorizationresult.c b/src/polkit/polkitauthorizationresult.c
index e9961c0..6786a5a 100644
--- a/src/polkit/polkitauthorizationresult.c
+++ b/src/polkit/polkitauthorizationresult.c
@@ -35,6 +35,11 @@
  * This class represents the result you get when checking for an authorization.
  */
 
+/**
+ * PolkitAuthorizationResult:
+ *
+ * The #PolkitAuthorizationResult struct should not be accessed directly.
+ */
 struct _PolkitAuthorizationResult
 {
   GObject parent_instance;
@@ -101,14 +106,16 @@ polkit_authorization_result_get_real (PolkitAuthorizationResult  *authorization_
 
 /**
  * polkit_authorization_result_new:
- * @is_authorized:
- * @is_challenge:
- * @details:
+ * @is_authorized: Whether the subject is authorized.
+ * @is_challenge: Whether the subject is authorized if more
+ * information is provided. Must be %FALSE unless @is_authorized is
+ * %TRUE.
+ * @details: Must be %NULL unless @is_authorized is %TRUE
  *
+ * Creates a new #PolkitAuthorizationResult object.
  *
- *
- * Returns:
- **/
+ * Returns: A #PolkitAuthorizationResult object. Free with g_object_unref().
+ */
 PolkitAuthorizationResult *
 polkit_authorization_result_new (gboolean                   is_authorized,
                                  gboolean                   is_challenge,
@@ -148,12 +155,12 @@ polkit_authorization_result_new (gboolean                   is_authorized,
 
 /**
  * polkit_authorization_result_get_is_authorized:
- * @result:
- *
+ * @result: A #PolkitAuthorizationResult.
  *
+ * Gets whether the subject is authorized.
  *
- * Returns:
- **/
+ * Returns: Whether the subject is authorized.
+ */
 gboolean
 polkit_authorization_result_get_is_authorized (PolkitAuthorizationResult *result)
 {
@@ -162,12 +169,12 @@ polkit_authorization_result_get_is_authorized (PolkitAuthorizationResult *result
 
 /**
  * polkit_authorization_result_get_is_challenge:
- * @result:
- *
+ * @result: A #PolkitAuthorizationResult.
  *
+ * Gets whether the subject is authorized if more information is provided.
  *
- * Returns:
- **/
+ * Returns: Whether the subject is authorized if more information is provided.
+ */
 gboolean
 polkit_authorization_result_get_is_challenge (PolkitAuthorizationResult *result)
 {
@@ -176,12 +183,13 @@ polkit_authorization_result_get_is_challenge (PolkitAuthorizationResult *result)
 
 /**
  * polkit_authorization_result_get_details:
- * @result:
+ * @result: A #PolkitAuthorizationResult.
  *
+ * Gets the details about the result.
  *
- *
- * Returns:
- **/
+ * Returns: A #PolkitDetails object. This object is owned by @result
+ * and should not be freed by the caller.
+ */
 PolkitDetails *
 polkit_authorization_result_get_details (PolkitAuthorizationResult *result)
 {
diff --git a/src/polkit/polkitdetails.c b/src/polkit/polkitdetails.c
index bef0704..2ef9e78 100644
--- a/src/polkit/polkitdetails.c
+++ b/src/polkit/polkitdetails.c
@@ -32,11 +32,17 @@
 /**
  * SECTION:polkitdetails
  * @title: PolkitDetails
- * @short_description: Details
+ * @short_description: Object used for passing details
+ * @stability: Stable
  *
  * An object used for passing details around.
  */
 
+/**
+ * PolkitDetails:
+ *
+ * The #PolkitDetails struct should not be accessed directly.
+ */
 struct _PolkitDetails
 {
   GObject parent_instance;
@@ -78,6 +84,13 @@ polkit_details_class_init (PolkitDetailsClass *klass)
   gobject_class->finalize = polkit_details_finalize;
 }
 
+/**
+ * polkit_details_new:
+ *
+ * Creates a new #PolkitDetails object.
+ *
+ * Returns: A #PolkitDetails object. Free with g_object_unref().
+ */
 PolkitDetails *
 polkit_details_new (void)
 {
@@ -88,6 +101,7 @@ polkit_details_new (void)
   return details;
 }
 
+/* private */
 PolkitDetails *
 polkit_details_new_for_hash (GHashTable *hash)
 {
@@ -100,12 +114,22 @@ polkit_details_new_for_hash (GHashTable *hash)
   return details;
 }
 
+/* private */
 GHashTable *
 polkit_details_get_hash (PolkitDetails *details)
 {
   return details->hash;
 }
 
+/**
+ * polkit_details_lookup:
+ * @details: A #PolkitDetails.
+ * @key: A key.
+ *
+ * Gets the value for @key on @details.
+ *
+ * Returns: %NULL if there is no value for @key, otherwise a string owned by @details.
+ */
 const gchar *
 polkit_details_lookup (PolkitDetails *details,
                        const gchar   *key)
@@ -116,6 +140,14 @@ polkit_details_lookup (PolkitDetails *details,
     return g_hash_table_lookup (details->hash, key);
 }
 
+/**
+ * polkit_details_insert:
+ * @details: A #PolkitDetails.
+ * @key: A key.
+ * @value: A value.
+ *
+ * Inserts a copy of @key and @value on @details.
+ */
 void
 polkit_details_insert (PolkitDetails *details,
                        const gchar   *key,
@@ -129,6 +161,14 @@ polkit_details_insert (PolkitDetails *details,
   g_hash_table_insert (details->hash, g_strdup (key), g_strdup (value));
 }
 
+/**
+ * polkit_details_get_keys:
+ * @details: A #PolkitDetails.
+ *
+ * Gets a list of all keys on @details.
+ *
+ * Returns: An array of strings that should be freed with g_strfreev().
+ */
 gchar **
 polkit_details_get_keys (PolkitDetails *details)
 {
diff --git a/src/polkit/polkitidentity.c b/src/polkit/polkitidentity.c
index f1eb852..08fd6ac 100644
--- a/src/polkit/polkitidentity.c
+++ b/src/polkit/polkitidentity.c
@@ -34,9 +34,10 @@
 /**
  * SECTION:polkitidentity
  * @title: PolkitIdentity
- * @short_description: Identities
+ * @short_description: Type for representing identities
  *
- * Identities.
+ * #PolkitIdentity is an abstract type for representing one or more
+ * identities.
  */
 
 static void
@@ -73,12 +74,31 @@ polkit_identity_get_type (void)
   return iface_type;
 }
 
+/**
+ * polkit_identity_hash:
+ * @identity: A #PolkitIdentity.
+ *
+ * Gets a hash code for @identity that can be used with e.g. g_hash_table_new().
+ *
+ * Returns: A hash code.
+ */
 guint
 polkit_identity_hash (PolkitIdentity *identity)
 {
   return POLKIT_IDENTITY_GET_IFACE (identity)->hash (identity);
 }
 
+/**
+ * polkit_identity_equal:
+ * @a: A #PolkitIdentity.
+ * @b: A #PolkitIdentity.
+ *
+ * Checks if @a and @b are equal, ie. represent the same identity.
+ *
+ * This function can be used in e.g. g_hash_table_new().
+ *
+ * Returns: %TRUE if @a and @b are equal, %FALSE otherwise.
+ */
 gboolean
 polkit_identity_equal (PolkitIdentity *a,
                       PolkitIdentity *b)
@@ -89,12 +109,32 @@ polkit_identity_equal (PolkitIdentity *a,
   return POLKIT_IDENTITY_GET_IFACE (a)->equal (a, b);
 }
 
+/**
+ * polkit_identity_to_string:
+ * @identity: A #PolkitIdentity.
+ *
+ * Serializes @identity to a string that can be used in
+ * polkit_identity_from_string().
+ *
+ * Returns: A string representing @identity. Free with g_free().
+ */
 gchar *
 polkit_identity_to_string (PolkitIdentity *identity)
 {
   return POLKIT_IDENTITY_GET_IFACE (identity)->to_string (identity);
 }
 
+/**
+ * polkit_identity_from_string:
+ * @str: A string obtained from polkit_identity_to_string().
+ * @error: Return location for error.
+ *
+ * Creates an object from @str that implements the #PolkitIdentity
+ * interface.
+ *
+ * Returns: A #PolkitIdentity or %NULL if @error is set. Free with
+ * g_object_unref().
+ */
 PolkitIdentity *
 polkit_identity_from_string  (const gchar   *str,
                              GError       **error)
diff --git a/src/polkit/polkitidentity.h b/src/polkit/polkitidentity.h
index 7d955e6..da908a2 100644
--- a/src/polkit/polkitidentity.h
+++ b/src/polkit/polkitidentity.h
@@ -38,10 +38,25 @@ G_BEGIN_DECLS
 #define POLKIT_IDENTITY_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), POLKIT_TYPE_IDENTITY, PolkitIdentityIface))
 
 #if 0
+/**
+ * PolkitIdentity:
+ *
+ * Generic type for all objects that can be used as identities.
+ */
 typedef struct _PolkitIdentity PolkitIdentity; /* Dummy typedef */
 #endif
 typedef struct _PolkitIdentityIface PolkitIdentityIface;
 
+/**
+ * PolkitIdentityIface:
+ * @parent_iface: The parent interface.
+ * @hash: Gets a hash value for a #PolkitIdentity.
+ * @equal: Checks if two #PolkitIdentity<!-- -->s are equal.
+ * @to_string: Serializes a #PolkitIdentity to a string that can be
+ * used in polkit_identity_from_string().
+ *
+ * An interface for identities.
+ */
 struct _PolkitIdentityIface
 {
   GTypeInterface parent_iface;
diff --git a/src/polkit/polkitsubject.c b/src/polkit/polkitsubject.c
index ba097f4..43be6b9 100644
--- a/src/polkit/polkitsubject.c
+++ b/src/polkit/polkitsubject.c
@@ -35,9 +35,10 @@
 /**
  * SECTION:polkitsubject
  * @title: PolkitSubject
- * @short_description: Subjects
+ * @short_description: Type for representing subjects
  *
- * Subjects.
+ * #PolkitSubject is an abstract type for representing one or more
+ * processes.
  */
 
 static void
@@ -74,12 +75,31 @@ polkit_subject_get_type (void)
   return iface_type;
 }
 
+/**
+ * polkit_subject_hash:
+ * @subject: A #PolkitSubject.
+ *
+ * Gets a hash code for @subject that can be used with e.g. g_hash_table_new().
+ *
+ * Returns: A hash code.
+ */
 guint
 polkit_subject_hash (PolkitSubject *subject)
 {
   return POLKIT_SUBJECT_GET_IFACE (subject)->hash (subject);
 }
 
+/**
+ * polkit_subject_equal:
+ * @a: A #PolkitSubject.
+ * @b: A #PolkitSubject.
+ *
+ * Checks if @a and @b are equal, ie. represent the same subject.
+ *
+ * This function can be used in e.g. g_hash_table_new().
+ *
+ * Returns: %TRUE if @a and @b are equal, %FALSE otherwise.
+ */
 gboolean
 polkit_subject_equal (PolkitSubject *a,
                       PolkitSubject *b)
@@ -90,12 +110,32 @@ polkit_subject_equal (PolkitSubject *a,
   return POLKIT_SUBJECT_GET_IFACE (a)->equal (a, b);
 }
 
+/**
+ * polkit_subject_to_string:
+ * @subject: A #PolkitSubject.
+ *
+ * Serializes @subject to a string that can be used in
+ * polkit_subject_from_string().
+ *
+ * Returns: A string representing @subject. Free with g_free().
+ */
 gchar *
 polkit_subject_to_string (PolkitSubject *subject)
 {
   return POLKIT_SUBJECT_GET_IFACE (subject)->to_string (subject);
 }
 
+/**
+ * polkit_subject_from_string:
+ * @str: A string obtained from polkit_subject_to_string().
+ * @error: Return location for error.
+ *
+ * Creates an object from @str that implements the #PolkitSubject
+ * interface.
+ *
+ * Returns: A #PolkitSubject or %NULL if @error is set. Free with
+ * g_object_unref().
+ */
 PolkitSubject *
 polkit_subject_from_string  (const gchar   *str,
                              GError       **error)
@@ -249,4 +289,3 @@ polkit_subject_get_real (PolkitSubject *subject)
 
   return real;
 }
-
diff --git a/src/polkit/polkitsubject.h b/src/polkit/polkitsubject.h
index 0ef8812..6eb8fef 100644
--- a/src/polkit/polkitsubject.h
+++ b/src/polkit/polkitsubject.h
@@ -38,10 +38,25 @@ G_BEGIN_DECLS
 #define POLKIT_SUBJECT_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), POLKIT_TYPE_SUBJECT, PolkitSubjectIface))
 
 #if 0
+/**
+ * PolkitSubject:
+ *
+ * Generic type for all objects that can be used as subjects.
+ */
 typedef struct _PolkitSubject PolkitSubject; /* Dummy typedef */
 #endif
 typedef struct _PolkitSubjectIface PolkitSubjectIface;
 
+/**
+ * PolkitSubjectIface:
+ * @parent_iface: The parent interface.
+ * @hash: Gets a hash value for a #PolkitSubject.
+ * @equal: Checks if two #PolkitSubject<!-- -->s are equal.
+ * @to_string: Serializes a #PolkitSubject to a string that can be
+ * used in polkit_subject_from_string().
+ *
+ * An interface for subjects.
+ */
 struct _PolkitSubjectIface
 {
   GTypeInterface parent_iface;
diff --git a/src/polkit/polkitsystembusname.c b/src/polkit/polkitsystembusname.c
index bd0c13d..44b71e5 100644
--- a/src/polkit/polkitsystembusname.c
+++ b/src/polkit/polkitsystembusname.c
@@ -31,11 +31,16 @@
 /**
  * SECTION:polkitsystembusname
  * @title: PolkitSystemBusName
- * @short_description: Unique system bus name
+ * @short_description: Unique system bus names
  *
- * Encapsulates a process with a unique name on the system bus.
+ * An object that represents a process owning a unique name on the system bus.
  */
 
+/**
+ * PolkitUnixSystemBusName:
+ *
+ * The #PolkitSystemBusName struct should not be accessed directly.
+ */
 struct _PolkitSystemBusName
 {
   GObject parent_instance;
@@ -144,12 +149,28 @@ polkit_system_bus_name_class_init (PolkitSystemBusNameClass *klass)
 
 }
 
+/**
+ * polkit_system_bus_name_get_name:
+ * @system_bus_name: A #PolkitSystemBusName.
+ *
+ * Gets the unique system bus name for @system_bus_name.
+ *
+ * Returns: The unique system bus name for @system_bus_name. Do not
+ * free, this string is owned by @system_bus_name.
+ */
 const gchar *
 polkit_system_bus_name_get_name (PolkitSystemBusName *system_bus_name)
 {
   return system_bus_name->name;
 }
 
+/**
+ * polkit_system_bus_name_set_name:
+ * @system_bus_name: A #PolkitSystemBusName.
+ * @name: A unique system bus name.
+ *
+ * Sets the unique system bus name for @system_bus_name.
+ */
 void
 polkit_system_bus_name_set_name (PolkitSystemBusName *system_bus_name,
                                  const gchar         *name)
@@ -158,6 +179,14 @@ polkit_system_bus_name_set_name (PolkitSystemBusName *system_bus_name,
   system_bus_name->name = g_strdup (name);
 }
 
+/**
+ * polkit_system_bus_name_new:
+ * @name: A unique system bus name.
+ *
+ * Creates a new #PolkitSystemBusName for @name.
+ *
+ * Returns: A #PolkitSystemBusName. Free with g_object_unref().
+ */
 PolkitSubject *
 polkit_system_bus_name_new (const gchar *name)
 {
diff --git a/src/polkit/polkitunixgroup.c b/src/polkit/polkitunixgroup.c
index fc8bf04..79db400 100644
--- a/src/polkit/polkitunixgroup.c
+++ b/src/polkit/polkitunixgroup.c
@@ -35,9 +35,14 @@
  * @title: PolkitUnixGroup
  * @short_description: Unix groups
  *
- * Encapsulates a UNIX group.
+ * An object representing a group identity on a UNIX system.
  */
 
+/**
+ * PolkitUnixGroup:
+ *
+ * The #PolkitUnixGroup struct should not be accessed directly.
+ */
 struct _PolkitUnixGroup
 {
   GObject parent_instance;
@@ -136,12 +141,27 @@ polkit_unix_group_class_init (PolkitUnixGroupClass *klass)
 
 }
 
+/**
+ * polkit_unix_group_get_gid:
+ * @group: A #PolkitUnixGroup.
+ *
+ * Gets the UNIX group id for @group.
+ *
+ * Returns: A UNIX group id.
+ */
 gid_t
 polkit_unix_group_get_gid (PolkitUnixGroup *group)
 {
   return group->gid;
 }
 
+/**
+ * polkit_unix_group_set_gid:
+ * @group: A #PolkitUnixGroup.
+ * @gid: A UNIX group id.
+ *
+ * Sets @gid for @group.
+ */
 void
 polkit_unix_group_set_gid (PolkitUnixGroup *group,
                           gid_t gid)
@@ -149,6 +169,14 @@ polkit_unix_group_set_gid (PolkitUnixGroup *group,
   group->gid = gid;
 }
 
+/**
+ * polkit_unix_group_new:
+ * @gid: A UNIX group id.
+ *
+ * Creates a new #PolkitUnixGroup object for @gid.
+ *
+ * Returns: A #PolkitUnixGroup object. Free with g_object_unref().
+ */
 PolkitIdentity *
 polkit_unix_group_new (gid_t gid)
 {
@@ -157,6 +185,16 @@ polkit_unix_group_new (gid_t gid)
                                        NULL));
 }
 
+/**
+ * polkit_unix_group_new_for_name:
+ * @name: A UNIX group name.
+ * @error: Return location for error.
+ *
+ * Creates a new #PolkitUnixGroup object for a group with the group name
+ * @name.
+ *
+ * Returns: A #PolkitUnixGroup object or %NULL if @error is set.
+ */
 PolkitIdentity *
 polkit_unix_group_new_for_name (const gchar    *name,
                                 GError        **error)
diff --git a/src/polkit/polkitunixprocess.c b/src/polkit/polkitunixprocess.c
index f3f67de..181f221 100644
--- a/src/polkit/polkitunixprocess.c
+++ b/src/polkit/polkitunixprocess.c
@@ -34,9 +34,18 @@
  * @title: PolkitUnixProcess
  * @short_description: Unix processs
  *
- * Encapsulates a UNIX process.
+ * An object for representing a UNIX process.
+ *
+ * To uniquely identify processes, both the process id and the start
+ * time of the process (a monotonic increasing value representing the
+ * time since the kernel was started) is used.
  */
 
+/**
+ * PolkitUnixProcess:
+ *
+ * The #PolkitUnixProcess struct should not be accessed directly.
+ */
 struct _PolkitUnixProcess
 {
   GObject parent_instance;
@@ -161,18 +170,41 @@ polkit_unix_process_class_init (PolkitUnixProcessClass *klass)
 
 }
 
+/**
+ * polkit_unix_process_get_pid:
+ * @process: A #PolkitUnixProcess.
+ *
+ * Gets the process id for @process.
+ *
+ * Returns: The process id for @process.
+ */
 pid_t
 polkit_unix_process_get_pid (PolkitUnixProcess *process)
 {
   return process->pid;
 }
 
+/**
+ * polkit_unix_process_get_start_time:
+ * @process: A #PolkitUnixProcess.
+ *
+ * Gets the start time of @process.
+ *
+ * Returns: The start time of @process.
+ */
 guint64
 polkit_unix_process_get_start_time (PolkitUnixProcess *process)
 {
   return process->start_time;
 }
 
+/**
+ * polkit_unix_process_set_pid:
+ * @process: A #PolkitUnixProcess.
+ * @pid: A process id.
+ *
+ * Sets @pid for @process.
+ */
 void
 polkit_unix_process_set_pid (PolkitUnixProcess *process,
                              pid_t              pid)
@@ -182,6 +214,17 @@ polkit_unix_process_set_pid (PolkitUnixProcess *process,
     process->start_time = get_start_time_for_pid (pid);
 }
 
+/**
+ * polkit_unix_process_new:
+ * @pid: The process id.
+ *
+ * Creates a new #PolkitUnixProcess for @pid. The start time of the
+ * process will be looked up in using e.g. the
+ * <filename>/proc</filename> filesystem depending on the platform in
+ * use.
+ *
+ * Returns: A #PolkitSubject. Free with g_object_unref().
+ */
 PolkitSubject *
 polkit_unix_process_new (pid_t pid)
 {
@@ -190,6 +233,15 @@ polkit_unix_process_new (pid_t pid)
                                        NULL));
 }
 
+/**
+ * polkit_unix_process_new_full:
+ * @pid: The process id.
+ * @start_time: The start time for @pid.
+ *
+ * Creates a new #PolkitUnixProcess object for @pid and @start_time.
+ *
+ * Returns: A #PolkitSubject. Free with g_object_unref().
+ */
 PolkitSubject *
 polkit_unix_process_new_full (pid_t pid,
                               guint64 start_time)
diff --git a/src/polkit/polkitunixsession.c b/src/polkit/polkitunixsession.c
index ff0c36a..66c762e 100644
--- a/src/polkit/polkitunixsession.c
+++ b/src/polkit/polkitunixsession.c
@@ -33,9 +33,16 @@
  * @title: PolkitUnixSession
  * @short_description: Unix sessions
  *
- * Encapsulates a login session on UNIX.
+ * An object that represents an user session.
+ *
+ * The session id is an opaque string obtained from ConsoleKit.
  */
 
+/**
+ * PolkitUnixSession:
+ *
+ * The #PolkitUnixSession struct should not be accessed directly.
+ */
 struct _PolkitUnixSession
 {
   GObject parent_instance;
@@ -132,12 +139,28 @@ polkit_unix_session_class_init (PolkitUnixSessionClass *klass)
 
 }
 
+/**
+ * polkit_unix_session_get_session_id:
+ * @session: A #PolkitUnixSession.
+ *
+ * Gets the session id for @session.
+ *
+ * Returns: The session id for @session. Do not free this string, it
+ * is owned by @session.
+ **/
 const gchar *
 polkit_unix_session_get_session_id (PolkitUnixSession *session)
 {
   return session->session_id;
 }
 
+/**
+ * polkit_unix_session_set_session_id:
+ * @session: A #PolkitUnixSession.
+ * @session_id: The session id.
+ *
+ * Sets the session id for @session to @session_id.
+ **/
 void
 polkit_unix_session_set_session_id (PolkitUnixSession *session,
                                     const gchar       *session_id)
@@ -146,6 +169,14 @@ polkit_unix_session_set_session_id (PolkitUnixSession *session,
   session->session_id = g_strdup (session_id);
 }
 
+/**
+ * polkit_unix_session_new:
+ * @session_id: The session id.
+ *
+ * Creates a new #PolkitUnixSession for @session_id.
+ *
+ * Returns: A #PolkitUnixSession. Free with g_object_unref().
+ **/
 PolkitSubject *
 polkit_unix_session_new (const gchar *session_id)
 {
diff --git a/src/polkit/polkitunixuser.c b/src/polkit/polkitunixuser.c
index a70d64a..e3d8327 100644
--- a/src/polkit/polkitunixuser.c
+++ b/src/polkit/polkitunixuser.c
@@ -35,9 +35,14 @@
  * @title: PolkitUnixUser
  * @short_description: Unix users
  *
- * Encapsulates a UNIX user.
+ * An object representing a user identity on a UNIX system.
  */
 
+/**
+ * PolkitUnixUser:
+ *
+ * The #PolkitUnixUser struct should not be accessed directly.
+ */
 struct _PolkitUnixUser
 {
   GObject parent_instance;
@@ -136,12 +141,27 @@ polkit_unix_user_class_init (PolkitUnixUserClass *klass)
 
 }
 
+/**
+ * polkit_unix_user_get_uid:
+ * @user: A #PolkitUnixUser.
+ *
+ * Gets the UNIX user id for @user.
+ *
+ * Returns: A UNIX user id.
+ */
 uid_t
 polkit_unix_user_get_uid (PolkitUnixUser *user)
 {
   return user->uid;
 }
 
+/**
+ * polkit_unix_user_set_uid:
+ * @user: A #PolkitUnixUser.
+ * @uid: A UNIX user id.
+ *
+ * Sets @uid for @user.
+ */
 void
 polkit_unix_user_set_uid (PolkitUnixUser *user,
                           uid_t uid)
@@ -149,6 +169,14 @@ polkit_unix_user_set_uid (PolkitUnixUser *user,
   user->uid = uid;
 }
 
+/**
+ * polkit_unix_user_new:
+ * @uid: A UNIX user id.
+ *
+ * Creates a new #PolkitUnixUser object for @uid.
+ *
+ * Returns: A #PolkitUnixUser object. Free with g_object_unref().
+ */
 PolkitIdentity *
 polkit_unix_user_new (uid_t uid)
 {
@@ -157,6 +185,16 @@ polkit_unix_user_new (uid_t uid)
                                         NULL));
 }
 
+/**
+ * polkit_unix_user_new_for_name:
+ * @name: A UNIX user name.
+ * @error: Return location for error.
+ *
+ * Creates a new #PolkitUnixUser object for a user with the user name
+ * @name.
+ *
+ * Returns: A #PolkitUnixUser object or %NULL if @error is set.
+ */
 PolkitIdentity *
 polkit_unix_user_new_for_name (const gchar    *name,
                                GError        **error)