Various doc cleanups

Signed-off-by: David Zeuthen <davidz@redhat.com>

14 files changed, 163 insertions, 80 deletions

diff --git a/src/polkit/polkitauthority.c b/src/polkit/polkitauthority.c
index f9f3971..404be18 100644
--- a/src/polkit/polkitauthority.c
+++ b/src/polkit/polkitauthority.c
@@ -449,8 +449,10 @@ authority_get_async_cb (GObject      *source_object,
  * Asynchronously gets a reference to the authority.
  *
  * This is an asynchronous failable function. When the result is
- * ready, @callback will be invoked and you can use
- * polkit_authority_get_finish() to get the result. See
+ * ready, @callback will be invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from and you
+ * can use polkit_authority_get_finish() to get the result. See
  * polkit_authority_get_sync() for the synchronous version.
  */
 void
@@ -534,8 +536,9 @@ polkit_authority_get_finish (GAsyncResult        *res,
  *
  * Synchronously gets a reference to the authority.
  *
- * This is a synchronous failable function. See
- * polkit_authority_get_async() for the synchronous version.
+ * This is a synchronous failable function - the calling thread is
+ * blocked until a reply is received. See polkit_authority_get_async()
+ * for the asynchronous version.
  *
  * Returns: A #PolkitAuthority. Free it with g_object_unref() when
  * done with it.
@@ -633,9 +636,11 @@ generic_async_cb (GObject      *source_obj,
  *
  * Asynchronously retrieves all registered actions.
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_enumerate_actions_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call polkit_authority_enumerate_actions_finish()
+ * to get the result of the operation.
  **/
 void
 polkit_authority_enumerate_actions (PolkitAuthority     *authority,
@@ -717,7 +722,9 @@ polkit_authority_enumerate_actions_finish (PolkitAuthority *authority,
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Synchronously retrieves all registered actions.
+ * Synchronously retrieves all registered actions - the calling thread
+ * is blocked until a reply is received. See
+ * polkit_authority_enumerate_actions() for the asynchronous version.
  *
  * Returns: A list of #PolkitActionDescription or %NULL if @error is set. The returned list
  * should be freed with g_list_free() after each element have been freed with g_object_unref().
@@ -838,13 +845,17 @@ check_authorization_cb (GDBusProxy    *proxy,
  * Asynchronously checks if @subject is authorized to perform the action represented
  * by @action_id.
  *
- * Note that #POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
- * SHOULD be passed ONLY if the event that triggered the authorization
- * check is stemming from an user action, e.g. the user pressing a
- * button or attaching a device.
- *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_check_authorization_finish() to get the result of
+ * Note that %POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
+ * <emphasis>SHOULD</emphasis> be passed <emphasis>ONLY</emphasis> if
+ * the event that triggered the authorization check is stemming from
+ * an user action, e.g. the user pressing a button or attaching a
+ * device.
+ *
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_check_authorization_finish() to get the result of
  * the operation.
  **/
 void
@@ -944,12 +955,22 @@ polkit_authority_check_authorization_finish (PolkitAuthority          *authority
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Checks if @subject is authorized to perform the action represented by @action_id.
+ * Checks if @subject is authorized to perform the action represented
+ * by @action_id.
+ *
+ * Note that %POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
+ * <emphasis>SHOULD</emphasis> be passed <emphasis>ONLY</emphasis> if
+ * the event that triggered the authorization check is stemming from
+ * an user action, e.g. the user pressing a button or attaching a
+ * device.
  *
- * Note that #POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION
- * SHOULD be passed ONLY if the event that triggered the authorization
- * check is stemming from an user action, e.g. the user pressing a
- * button or attaching a device.
+ * Note the calling thread is blocked until a reply is received. You
+ * should therefore <emphasis>NEVER</emphasis> do this from a GUI
+ * thread or a daemon service thread when using the
+ * %POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION flag. This
+ * is because it may potentially take minutes (or even hours) for the
+ * operation to complete because it involves waiting for the user to
+ * authenticate.
  *
  * Returns: A #PolkitAuthorizationResult or %NULL if @error is set. Free with g_object_unref().
  */
@@ -995,9 +1016,12 @@ polkit_authority_check_authorization_sync (PolkitAuthority               *author
  *
  * Asynchronously registers an authentication agent.
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_register_authentication_agent_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_register_authentication_agent_finish() to get the
+ * result of the operation.
  **/
 void
 polkit_authority_register_authentication_agent (PolkitAuthority      *authority,
@@ -1083,7 +1107,10 @@ polkit_authority_register_authentication_agent_finish (PolkitAuthority *authorit
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Registers an authentication agent.
+ * Registers an authentication agent. The calling thread is blocked
+ * until a reply is received. See
+ * polkit_authority_register_authentication_agent() for the
+ * asynchronous version.
  *
  * Returns: %TRUE if the authentication agent was successfully registered, %FALSE if @error is set.
  **/
@@ -1120,7 +1147,6 @@ polkit_authority_register_authentication_agent_sync (PolkitAuthority     *author
  * polkit_authority_unregister_authentication_agent:
  * @authority: A #PolkitAuthority.
  * @subject: The subject the authentication agent is for, typically a #PolkitUnixSession object.
- * @locale: The locale of the authentication agent.
  * @object_path: The object path for the authentication agent.
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
@@ -1128,9 +1154,12 @@ polkit_authority_register_authentication_agent_sync (PolkitAuthority     *author
  *
  * Asynchronously unregisters an authentication agent.
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_unregister_authentication_agent_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_unregister_authentication_agent_finish() to get
+ * the result of the operation.
  **/
 void
 polkit_authority_unregister_authentication_agent (PolkitAuthority      *authority,
@@ -1208,12 +1237,14 @@ polkit_authority_unregister_authentication_agent_finish (PolkitAuthority *author
  * polkit_authority_unregister_authentication_agent_sync:
  * @authority: A #PolkitAuthority.
  * @subject: The subject the authentication agent is for, typically a #PolkitUnixSession object.
- * @locale: The locale of the authentication agent.
  * @object_path: The object path for the authentication agent.
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Unregisters an authentication agent.
+ * Unregisters an authentication agent. The calling thread is blocked
+ * until a reply is received. See
+ * polkit_authority_unregister_authentication_agent() for the
+ * asynchronous version.
  *
  * Returns: %TRUE if the authentication agent was successfully unregistered, %FALSE if @error is set.
  **/
@@ -1259,9 +1290,12 @@ polkit_authority_unregister_authentication_agent_sync (PolkitAuthority     *auth
  * This function is only used by the privileged bits of an authentication agent.
  * It will fail if the caller is not sufficiently privileged (typically uid 0).
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_authentication_agent_response_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_authentication_agent_response_finish() to get the
+ * result of the operation.
  **/
 void
 polkit_authority_authentication_agent_response (PolkitAuthority      *authority,
@@ -1347,6 +1381,10 @@ polkit_authority_authentication_agent_response_finish (PolkitAuthority *authorit
  * authentication request identified by @cookie. See polkit_authority_authentication_agent_response()
  * for limitations on who is allowed is to call this method.
  *
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_authentication_agent_response() for the
+ * asynchronous version.
+ *
  * Returns: %TRUE if @authority acknowledged the call, %FALSE if @error is set.
  **/
 gboolean
@@ -1386,9 +1424,12 @@ polkit_authority_authentication_agent_response_sync (PolkitAuthority     *author
  *
  * Asynchronously gets all temporary authorizations for @subject.
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_enumerate_temporary_authorizations_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_enumerate_temporary_authorizations_finish() to get
+ * the result of the operation.
  **/
 void
 polkit_authority_enumerate_temporary_authorizations (PolkitAuthority     *authority,
@@ -1489,6 +1530,10 @@ polkit_authority_enumerate_temporary_authorizations_finish (PolkitAuthority *aut
  *
  * Synchronousky gets all temporary authorizations for @subject.
  *
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_enumerate_temporary_authorizations() for the
+ * asynchronous version.
+ *
  * Returns: A list of #PolkitTemporaryAuthorization objects or %NULL if @error is set. The returned list
  * should be freed with g_list_free() after each element have been freed with g_object_unref().
  **/
@@ -1527,9 +1572,12 @@ polkit_authority_enumerate_temporary_authorizations_sync (PolkitAuthority     *a
  *
  * Asynchronously revokes all temporary authorizations for @subject.
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_revoke_temporary_authorizations_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_revoke_temporary_authorizations_finish() to get
+ * the result of the operation.
  **/
 void
 polkit_authority_revoke_temporary_authorizations (PolkitAuthority     *authority,
@@ -1608,6 +1656,10 @@ polkit_authority_revoke_temporary_authorizations_finish (PolkitAuthority *author
  *
  * Synchronously revokes all temporary authorization from @subject.
  *
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_revoke_temporary_authorizations() for the
+ * asynchronous version.
+ *
  * Returns: %TRUE if the temporary authorization was revoked, %FALSE if error is set.
  **/
 gboolean
@@ -1645,9 +1697,12 @@ polkit_authority_revoke_temporary_authorizations_sync (PolkitAuthority     *auth
  *
  * Asynchronously revoke a temporary authorization.
  *
- * When the operation is finished, @callback will be invoked. You can then
- * call polkit_authority_revoke_temporary_authorization_by_id_finish() to get the result of
- * the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_authority_revoke_temporary_authorization_by_id_finish() to
+ * get the result of the operation.
  */
 void
 polkit_authority_revoke_temporary_authorization_by_id (PolkitAuthority     *authority,
@@ -1721,6 +1776,10 @@ polkit_authority_revoke_temporary_authorization_by_id_finish (PolkitAuthority *a
  *
  * Synchronously revokes a temporary authorization.
  *
+ * The calling thread is blocked until a reply is received. See
+ * polkit_authority_revoke_temporary_authorization_by_id() for the
+ * asynchronous version.
+ *
  * Returns: %TRUE if the temporary authorization was revoked, %FALSE if error is set.
  **/
 gboolean
@@ -1755,7 +1814,7 @@ polkit_authority_revoke_temporary_authorization_by_id_sync (PolkitAuthority
  * The unique name on the system message bus of the owner of the name
  * <literal>org.freedesktop.PolicyKit1</literal> or %NULL if no-one
  * currently owns the name. You may connect to the #GObject::notify
- * signal to track changes to the #PolkitAuthority::owner property.
+ * signal to track changes to the #PolkitAuthority:owner property.
  *
  * Returns: (allow-none): %NULL or a string that should be freed with g_free().
  **/
diff --git a/src/polkit/polkitauthorityfeatures.h b/src/polkit/polkitauthorityfeatures.h
index 35a3ecc..01aea78 100644
--- a/src/polkit/polkitauthorityfeatures.h
+++ b/src/polkit/polkitauthorityfeatures.h
@@ -35,7 +35,6 @@ G_BEGIN_DECLS
  * @POLKIT_AUTHORITY_FEATURES_NONE: No flags set.
  * @POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION: The authority supports temporary authorizations
  * that can be obtained through authentication.
- * @POLKIT_AUTHORITY_FEATURES_LOCKDOWN: The authority supports the XXX method.
  *
  * Flags describing features supported by the Authority implementation.
  */
@@ -43,7 +42,6 @@ typedef enum
 {
   POLKIT_AUTHORITY_FEATURES_NONE                    = 0,
   POLKIT_AUTHORITY_FEATURES_TEMPORARY_AUTHORIZATION = (1<<0),
-  POLKIT_AUTHORITY_FEATURES_LOCKDOWN                = (1<<1)
 } PolkitAuthorityFeatures;
 
 G_END_DECLS
diff --git a/src/polkit/polkitidentity.h b/src/polkit/polkitidentity.h
index da908a2..50491ad 100644
--- a/src/polkit/polkitidentity.h
+++ b/src/polkit/polkitidentity.h
@@ -70,7 +70,7 @@ struct _PolkitIdentityIface
 };
 
 GType          polkit_identity_get_type      (void) G_GNUC_CONST;
-guint          polkit_identity_hash          (PolkitIdentity *a);
+guint          polkit_identity_hash          (PolkitIdentity *identity);
 gboolean       polkit_identity_equal         (PolkitIdentity *a,
                                               PolkitIdentity *b);
 gchar          *polkit_identity_to_string    (PolkitIdentity *identity);
diff --git a/src/polkit/polkitsubject.c b/src/polkit/polkitsubject.c
index 51e60e0..d193eb2 100644
--- a/src/polkit/polkitsubject.c
+++ b/src/polkit/polkitsubject.c
@@ -140,9 +140,11 @@ polkit_subject_to_string (PolkitSubject *subject)
  *
  * Asynchronously checks if @subject exists.
  *
- * When the operation is finished, @callback will be invoked. You can
- * then call polkit_subject_exists_finish() to get the result of the
- * operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call polkit_subject_exists_finish() to get the
+ * result of the operation.
  **/
 void
 polkit_subject_exists (PolkitSubject       *subject,
@@ -189,8 +191,9 @@ polkit_subject_exists_finish (PolkitSubject   *subject,
  *
  * Checks if @subject exists.
  *
- * This is a synchronous blocking call, see polkit_subject_exists()
- * for the asynchronous version.
+ * This is a synchronous blocking call - the calling thread is blocked
+ * until a reply is received. See polkit_subject_exists() for the
+ * asynchronous version.
  *
  * Returns: %TRUE if the subject exists, %FALSE if not or @error is set.
  */
diff --git a/src/polkit/polkitsystembusname.c b/src/polkit/polkitsystembusname.c
index 9bd074b..41f2762 100644
--- a/src/polkit/polkitsystembusname.c
+++ b/src/polkit/polkitsystembusname.c
@@ -346,7 +346,8 @@ subject_iface_init (PolkitSubjectIface *subject_iface)
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: (allow-none): Return location for error or %NULL.
  *
- * Synchronously gets a #PolkitUnixProcess object for @system_bus_name.
+ * Synchronously gets a #PolkitUnixProcess object for @system_bus_name
+ * - the calling thread is blocked until a reply is received.
  *
  * Returns: (allow-none): A #PolkitUnixProcess object or %NULL if @error is set.
  **/
diff --git a/src/polkit/polkitunixsession.c b/src/polkit/polkitunixsession.c
index a72e453..c466561 100644
--- a/src/polkit/polkitunixsession.c
+++ b/src/polkit/polkitunixsession.c
@@ -242,9 +242,12 @@ polkit_unix_session_new (const gchar *session_id)
  * Asynchronously creates a new #PolkitUnixSession object for the
  * process with process id @pid.
  *
- * When the operation is finished, @callback will be invoked. You can
- * then call polkit_unix_session_new_for_process_finish() to get the
- * result of the operation.
+ * When the operation is finished, @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method
+ * from. You can then call
+ * polkit_unix_session_new_for_process_finish() to get the result of
+ * the operation.
  *
  * This method constructs the object asynchronously, for the synchronous and blocking version
  * use polkit_unix_session_new_for_process_sync().
@@ -305,7 +308,8 @@ polkit_unix_session_new_for_process_finish (GAsyncResult   *res,
  *
  * Creates a new #PolkitUnixSession for the process with process id @pid.
  *
- * This is a synchronous call that does blocking IO, for the asynchronous version, use
+ * This is a synchronous call - the calling thread is blocked until a
+ * reply is received. For the asynchronous version, see
  * polkit_unix_session_new_for_process().
  *
  * Returns: (allow-none): A #PolkitUnixSession for @pid or %NULL if
diff --git a/src/polkitagent/polkitagentlistener.c b/src/polkitagent/polkitagentlistener.c
index 52d71ff..5e71ec1 100644
--- a/src/polkitagent/polkitagentlistener.c
+++ b/src/polkitagent/polkitagentlistener.c
@@ -33,15 +33,17 @@
  *
  * #PolkitAgentListener is an abstract base class used for implementing authentication
  * agents. To implement an authentication agent, simply subclass #PolkitAgentListener and
- * implement the @initiate_authentication and @initiate_authentication_finish VFuncs.
+ * implement the @initiate_authentication and @initiate_authentication_finish methods.
  *
- * Typically authentication agents use #PolkitAgentSession to authenticate users (via
- * passwords) and communicate back the authentication result to the PolicyKit daemon.
- * This is however not requirement. Depending on the system an authentication agent
- * may use other means (such as a Yes/No dialog) to obtain sufficient evidence that
- * the user is one of the requested identities.
+ * Typically authentication agents use #PolkitAgentSession to
+ * authenticate users (via passwords) and communicate back the
+ * authentication result to the PolicyKit daemon.  This is however not
+ * requirement. Depending on the system an authentication agent may
+ * use other means (such as a Yes/No dialog) to obtain sufficient
+ * evidence that the user is one of the requested identities.
  *
- * To register a #PolkitAgentListener with the PolicyKit daemon, use polkit_agent_register_listener().
+ * To register a #PolkitAgentListener with the PolicyKit daemon, use
+ * polkit_agent_listener_register().
  */
 
 typedef struct
@@ -381,6 +383,8 @@ server_thread_func (gpointer user_data)
  * example another authentication agent may already be registered for
  * @subject.
  *
+ * Note that the calling thread is blocked until a reply is received.
+ *
  * Returns: %NULL if @error is set, otherwise a registration handle
  * that can be used with polkit_agent_listener_unregister().
  */
@@ -703,17 +707,24 @@ polkit_agent_listener_class_init (PolkitAgentListenerClass *klass)
  * @callback: Function to call when the user is done authenticating.
  * @user_data: Data to pass to @callback.
  *
- * Called on a registered authentication agent (see polkit_agent_register_listener()) when
- * the user owning the session needs to prove he is one of the identities listed in @identities.
+ * Called on a registered authentication agent (see
+ * polkit_agent_listener_register()) when the user owning the session
+ * needs to prove he is one of the identities listed in @identities.
  *
- * When the user is done authenticating (for example by dismissing an authentication dialog
- * or by successfully entering a password or otherwise proving the user is one of the
- * identities in @identities), @callback will be invoked. The caller then calls
- * polkit_agent_listener_initiate_authentication_finish() to get the result.
+ * When the user is done authenticating (for example by dismissing an
+ * authentication dialog or by successfully entering a password or
+ * otherwise proving the user is one of the identities in
+ * @identities), @callback will be invoked. The caller then calls
+ * polkit_agent_listener_initiate_authentication_finish() to get the
+ * result.
  *
- * #PolkitAgentListener derived subclasses imlementing this method MUST not
- * ignore @cancellable; callers of this function can and will use it.
- **/
+ * #PolkitAgentListener derived subclasses imlementing this method
+ * <emphasis>MUST</emphasis> not ignore @cancellable; callers of this
+ * function can and will use it. Additionally, @callback must be
+ * invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread that this method is called from.
+ */
 void
 polkit_agent_listener_initiate_authentication (PolkitAgentListener  *listener,
                                                const gchar          *action_id,
diff --git a/src/polkitagent/polkitagentsession.c b/src/polkitagent/polkitagentsession.c
index 3780b7c..2d72348 100644
--- a/src/polkitagent/polkitagentsession.c
+++ b/src/polkitagent/polkitagentsession.c
@@ -429,7 +429,11 @@ polkit_agent_session_response (PolkitAgentSession *session,
  * polkit_agent_session_initiate:
  * @session: A #PolkitAgentSession.
  *
- * Initiates the authentication session.
+ * Initiates the authentication session. Before calling this method,
+ * make sure to connect to the various signals. The signals will be
+ * emitted in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> that this method is invoked from.
  *
  * Use polkit_agent_session_cancel() to cancel the session.
  **/
diff --git a/src/polkitbackend/polkitbackendactionpool.c b/src/polkitbackend/polkitbackendactionpool.c
index 30e9540..55eecf5 100644
--- a/src/polkitbackend/polkitbackendactionpool.c
+++ b/src/polkitbackend/polkitbackendactionpool.c
@@ -30,7 +30,7 @@
 
 #include "polkitbackendactionpool.h"
 
-/**
+/* <internal>
  * SECTION:polkitbackendactionpool
  * @title: PolkitBackendActionPool
  * @short_description: Registered actions
diff --git a/src/polkitbackend/polkitbackendauthority.h b/src/polkitbackend/polkitbackendauthority.h
index 7c6dc6d..bfc0480 100644
--- a/src/polkitbackend/polkitbackendauthority.h
+++ b/src/polkitbackend/polkitbackendauthority.h
@@ -62,7 +62,10 @@ struct _PolkitBackendAuthority
 /**
  * PolkitBackendAuthorityClass:
  * @parent_class: The parent class.
- * @changed: Function pointer for #PolkitBackendAuthorityClass::changed signal.
+ * @get_name: Function pointer for the polkit_backend_authority_get_name() function.
+ * @get_version: Function pointer for the polkit_backend_authority_get_version() function.
+ * @get_features: Function pointer for the polkit_backend_authority_get_features() function.
+ * @changed: Function pointer for #PolkitBackendAuthority::changed signal.
  * @enumerate_actions: Enumerates registered actions on the
  * system. See polkit_backend_authority_enumerate_actions() for
  * details.
@@ -100,7 +103,7 @@ struct _PolkitBackendAuthority
  * the operation. See polkit_backend_authority_revoke_temporary_authorization_by_id()
  * for details.
  *
- * VFuncs that authority backends need to implement.
+ * Class structure for #PolkitBackendAuthority.
  */
 struct _PolkitBackendAuthorityClass
 {
diff --git a/src/polkitbackend/polkitbackendconfigsource.c b/src/polkitbackend/polkitbackendconfigsource.c
index 465da96..abdb089 100644
--- a/src/polkitbackend/polkitbackendconfigsource.c
+++ b/src/polkitbackend/polkitbackendconfigsource.c
@@ -24,7 +24,7 @@
 #include <polkit/polkit.h>
 #include "polkitbackendconfigsource.h"
 
-/**
+/* <internal>
  * SECTION:polkitbackendconfigsource
  * @title: PolkitBackendConfigSource
  * @short_description: Access configuration files
diff --git a/src/polkitbackend/polkitbackendinteractiveauthority.c b/src/polkitbackend/polkitbackendinteractiveauthority.c
index 31e60df..386a4c9 100644
--- a/src/polkitbackend/polkitbackendinteractiveauthority.c
+++ b/src/polkitbackend/polkitbackendinteractiveauthority.c
@@ -1138,7 +1138,7 @@ check_authorization_sync (PolkitBackendAuthority         *authority,
  *
  * The default implementation returns a list with a single element for the super user.
  *
- * Returns: A list of #PolkitIdentities. Free each element
+ * Returns: A list of #PolkitIdentity objects. Free each element
  *     g_object_unref(), then free the list with g_list_free().
  */
 GList *
diff --git a/src/polkitbackend/polkitbackendlocalauthorizationstore.c b/src/polkitbackend/polkitbackendlocalauthorizationstore.c
index b959269..20e9682 100644
--- a/src/polkitbackend/polkitbackendlocalauthorizationstore.c
+++ b/src/polkitbackend/polkitbackendlocalauthorizationstore.c
@@ -25,7 +25,7 @@
 #include <polkit/polkit.h>
 #include "polkitbackendlocalauthorizationstore.h"
 
-/**
+/* <internal>
  * SECTION:polkitbackendlocalauthorizationstore
  * @title: PolkitBackendLocalAuthorizationStore
  * @short_description: Watches a directory for authorization files
diff --git a/src/polkitbackend/polkitbackendsessionmonitor.c b/src/polkitbackend/polkitbackendsessionmonitor.c
index 877d69e..e91ad84 100644
--- a/src/polkitbackend/polkitbackendsessionmonitor.c
+++ b/src/polkitbackend/polkitbackendsessionmonitor.c
@@ -31,7 +31,7 @@
 
 #define CKDB_PATH "/var/run/ConsoleKit/database"
 
-/**
+/* <internal>
  * SECTION:polkitbackendsessionmonitor
  * @title: PolkitBackendSessionMonitor
  * @short_description: Monitor sessions