From 607cfb73774b16cf1498f1791183b67a7684819c Mon Sep 17 00:00:00 2001
From: Alexander Kanavin <alexander.kanavin@intel.com>
Date: Fri, 30 Aug 2013 16:22:44 +0300
Subject: [PATCH] docs: fix up SignonAuthService docs

---
 docs/reference/Makefile.am            |  2 +-
 libgsignon-glib/signon-auth-service.c | 34 +++++++++++++++++++++++----
 libgsignon-glib/signon-auth-service.h |  1 +
 3 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 3deeb7e..3ae2f89 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -33,7 +33,7 @@ MKDB_OPTIONS=--source-dir=$(top_srcdir)/libgsignon-glib --sgml-mode --output-for
 
 # Extra options to supply to gtkdoc-fixref. Not normally needed.
 # e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
-FIXXREF_OPTIONS=
+FIXXREF_OPTIONS=--extra-dir=../../../accounts-sso.gsignond/docs/html
 
 # Used for dependencies. The docs will be rebuilt if any of these change.
 # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
diff --git a/libgsignon-glib/signon-auth-service.c b/libgsignon-glib/signon-auth-service.c
index cfd569b..71d5ef3 100644
--- a/libgsignon-glib/signon-auth-service.c
+++ b/libgsignon-glib/signon-auth-service.c
@@ -26,9 +26,10 @@
 /**
  * SECTION:signon-auth-service
  * @title: SignonAuthService
- * @short_description: The authorization service object
+ * @short_description: the authorization service object
  *
- * The #SignonAuthService is the main object in this library.
+ * The #SignonAuthService is the main object in this library. It provides top-level
+ * functions to query existing identities, available methods and their mechanisms.
  */
 
 #include "signon-auth-service.h"
@@ -194,7 +195,7 @@ auth_query_mechanisms_cb (GObject *object, GAsyncResult *res,
  * @cb: (scope async): callback to be invoked.
  * @user_data: user data.
  *
- * Lists all the available methods.
+ * Lists all the available authentication methods.
  */
 void
 signon_auth_service_query_methods (SignonAuthService *auth_service,
@@ -238,7 +239,7 @@ signon_auth_service_query_methods (SignonAuthService *auth_service,
  * @cb: (scope async): callback to be invoked.
  * @user_data: user data.
  *
- * Lists all the available mechanisms.
+ * Lists all the available mechanisms for an authentication method.
  */
 void
 signon_auth_service_query_mechanisms (SignonAuthService *auth_service,
@@ -322,7 +323,30 @@ auth_query_identities_cb (GObject *object, GAsyncResult *res,
  * @cb: (scope async): callback to be invoked.
  * @user_data: user data.
  *
- * Query identities.
+ * Query available identities, possibly applying a filter. 
+ *
+ * @filter is a #GHashTable that contains filter conditions in the form of 
+ * string keys and #GVariant values. Currently the following keys are supported:
+ * 
+ * - "Owner". The value should be a #SignonSecurityContext (use 
+ * signon_security_context_build_variant() to create a #GVariant). 
+ * Identites whose owner doesn't match will be filtered out. This key has
+ * effect only if the requesting application is a keychain application as determined
+ * by #GSignondAccessControlManager.
+ * - "Type". The value should be a #SignonIdentityType.
+ * - "Caption". The value is a string, and only those identites whose caption
+ * begins with the supplied value will be returned.
+ * 
+ * The meaning of @application_context is explained in #SignonSecurityContext.
+ * It is used by #GSignondAccessControlManager to determine if the requesting 
+ * application is a keychain application. If it is, then all identites will be
+ * returned (subject to "Owner" key in @filter). If it's not, then only the
+ * identites which the application owns will be returned (but "Type" and "Caption"
+ * can still be set in the @filter).
+ * 
+ */
+/*
+ * //FIXME: @filter should come with setters and getters!
  */
 void
 signon_auth_service_query_identities (SignonAuthService *auth_service,
diff --git a/libgsignon-glib/signon-auth-service.h b/libgsignon-glib/signon-auth-service.h
index 946e172..204756c 100644
--- a/libgsignon-glib/signon-auth-service.h
+++ b/libgsignon-glib/signon-auth-service.h
@@ -42,6 +42,7 @@ typedef struct _SignonAuthService SignonAuthService;
 
 /**
  * SignonAuthServiceClass:
+ * @parent_class: a reference to the parent class
  *
  * Opaque struct. Use the accessor functions below.
  */
-- 
2.34.1