Add some more API docs

docs/polkit/polkit-1-sections.txt

@@ -16,6 +16,37 @@ POLKIT_IS_UNIX_USER_CLASS
 POLKIT_UNIX_USER_GET_CLASS
 </SECTION>
 
+<SECTION>
+<FILE>polkitauthority</FILE>
+PolkitAuthority
+PolkitCheckAuthorizationFlags
+polkit_authority_get
+polkit_authority_check_authorization
+polkit_authority_check_authorization_finish
+polkit_authority_enumerate_actions
+polkit_authority_enumerate_actions_finish
+polkit_authority_register_authentication_agent
+polkit_authority_register_authentication_agent_finish
+polkit_authority_unregister_authentication_agent
+polkit_authority_unregister_authentication_agent_finish
+polkit_authority_authentication_agent_response
+polkit_authority_authentication_agent_response_finish
+polkit_authority_check_authorization_sync
+polkit_authority_enumerate_actions_sync
+polkit_authority_register_authentication_agent_sync
+polkit_authority_unregister_authentication_agent_sync
+polkit_authority_authentication_agent_response_sync
+<SUBSECTION Standard>
+PolkitAuthorityClass
+POLKIT_AUTHORITY
+POLKIT_IS_AUTHORITY
+POLKIT_TYPE_AUTHORITY
+polkit_authority_get_type
+POLKIT_AUTHORITY_CLASS
+POLKIT_IS_AUTHORITY_CLASS
+POLKIT_AUTHORITY_GET_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>polkitauthoritymanager</FILE>
 PolkitAuthorityManager
@@ -46,37 +77,6 @@ POLKIT_IS_AUTHORITY_MANAGER_CLASS
 POLKIT_AUTHORITY_MANAGER_GET_CLASS
 </SECTION>
 
-<SECTION>
-<FILE>polkitauthority</FILE>
-PolkitAuthority
-PolkitCheckAuthorizationFlags
-polkit_authority_get
-polkit_authority_enumerate_actions_sync
-polkit_authority_check_authorization_sync
-polkit_authority_register_authentication_agent_sync
-polkit_authority_unregister_authentication_agent_sync
-polkit_authority_authentication_agent_response_sync
-polkit_authority_enumerate_actions
-polkit_authority_enumerate_actions_finish
-polkit_authority_check_authorization
-polkit_authority_check_authorization_finish
-polkit_authority_register_authentication_agent
-polkit_authority_register_authentication_agent_finish
-polkit_authority_unregister_authentication_agent
-polkit_authority_unregister_authentication_agent_finish
-polkit_authority_authentication_agent_response
-polkit_authority_authentication_agent_response_finish
-<SUBSECTION Standard>
-PolkitAuthorityClass
-POLKIT_AUTHORITY
-POLKIT_IS_AUTHORITY
-POLKIT_TYPE_AUTHORITY
-polkit_authority_get_type
-POLKIT_AUTHORITY_CLASS
-POLKIT_IS_AUTHORITY_CLASS
-POLKIT_AUTHORITY_GET_CLASS
-</SECTION>
-
 <SECTION>
 <FILE>polkitauthorizationresult</FILE>
 PolkitAuthorizationResult
@@ -262,10 +262,10 @@ polkit_implicit_authorization_get_type
 <SECTION>
 <FILE>polkiterror</FILE>
 POLKIT_ERROR
-POLKIT_TYPE_ERROR
 PolkitError
 <SUBSECTION Standard>
 polkit_error_quark
+POLKIT_TYPE_ERROR
 polkit_error_get_type
 </SECTION>
 

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;
 }
-

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

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)
 {

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)
 {

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)

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;

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;
 }
-

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