GNOME.org
 

[libgdata] Added API documentation for GDataContactsQuery and GDataContactsService

commit cf5e5c5813737e2bd468beb2fdd41ddece3b7089
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Apr 20 07:57:45 2009 +0100

    Added API documentation for GDataContactsQuery and GDataContactsService
---
 docs/reference/gdata-docs.xml                    |    6 +
 docs/reference/gdata-sections.txt                |   48 ++++++++
 gdata/gdata-service.c                            |    2 +-
 gdata/services/contacts/gdata-contacts-query.c   |  138 ++++++++++++++++++++-
 gdata/services/contacts/gdata-contacts-query.h   |   13 ++-
 gdata/services/contacts/gdata-contacts-service.c |   67 ++++++++++-
 gdata/services/contacts/gdata-contacts-service.h |   11 ++
 7 files changed, 275 insertions(+), 10 deletions(-)

diff --git a/docs/reference/gdata-docs.xml b/docs/reference/gdata-docs.xml
index c947413..83a3dd0 100644
--- a/docs/reference/gdata-docs.xml
+++ b/docs/reference/gdata-docs.xml
@@ -31,6 +31,12 @@
 		<xi:include href="xml/gdata-youtube-video.xml"/>
 	</chapter>
 
+	<chapter>
+		<title>Google Contacts API</title>
+		<xi:include href="xml/gdata-contacts-service.xml"/>
+		<xi:include href="xml/gdata-contacts-query.xml"/>
+	</chapter>
+
 	<chapter id="object-tree">
 		<title>Object Hierarchy</title>
 		<xi:include href="xml/tree_index.sgml"/>
diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index 99692da..8a56df5 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -282,3 +282,51 @@ gdata_youtube_video_get_type
 <SUBSECTION Private>
 GDataYouTubeVideoPrivate
 </SECTION>
+
+<SECTION>
+<FILE>gdata-contacts-service</FILE>
+<TITLE>GDataContactsService</TITLE>
+GDataContactsService
+GDataContactsServiceClass
+gdata_contacts_service_new
+gdata_contacts_service_query_contacts
+gdata_contacts_service_query_contacts_async
+gdata_contacts_service_insert_contact
+<SUBSECTION Standard>
+gdata_contacts_service_get_type
+GDATA_CONTACTS_SERVICE
+GDATA_CONTACTS_SERVICE_CLASS
+GDATA_CONTACTS_SERVICE_GET_CLASS
+GDATA_IS_CONTACTS_SERVICE
+GDATA_IS_CONTACTS_SERVICE_CLASS
+GDATA_TYPE_CONTACTS_SERVICE
+<SUBSECTION Private>
+GDataContactsServicePrivate
+</SECTION>
+
+<SECTION>
+<FILE>gdata-contacts-query</FILE>
+<TITLE>GDataContactsQuery</TITLE>
+GDataContactsQuery
+GDataContactsQueryClass
+gdata_contacts_query_new
+gdata_contacts_query_new_with_limits
+gdata_contacts_query_get_order_by
+gdata_contacts_query_set_order_by
+gdata_contacts_query_show_deleted
+gdata_contacts_query_set_show_deleted
+gdata_contacts_query_get_sort_order
+gdata_contacts_query_set_sort_order
+gdata_contacts_query_get_group
+gdata_contacts_query_set_group
+<SUBSECTION Standard>
+gdata_contacts_query_get_type
+GDATA_CONTACTS_QUERY
+GDATA_CONTACTS_QUERY_CLASS
+GDATA_CONTACTS_QUERY_GET_CLASS
+GDATA_IS_CONTACTS_QUERY
+GDATA_IS_CONTACTS_QUERY_CLASS
+GDATA_TYPE_CONTACTS_QUERY
+<SUBSECTION Private>
+GDataContactsQueryPrivate
+</SECTION>
diff --git a/gdata/gdata-service.c b/gdata/gdata-service.c
index f28d556..3cb7ed5 100644
--- a/gdata/gdata-service.c
+++ b/gdata/gdata-service.c
@@ -939,7 +939,7 @@ gdata_service_query (GDataService *self, const gchar *feed_uri, GDataQuery *quer
  * gdata_service_insert_entry:
  * @self: a #GDataService
  * @upload_uri: the URI to which the upload should be sent
- * @entry: the #GDataEntry to upload
+ * @entry: the #GDataEntry to insert
  * @cancellable: optional #GCancellable object, or %NULL
  * @error: a #GError, or %NULL
  *
diff --git a/gdata/services/contacts/gdata-contacts-query.c b/gdata/services/contacts/gdata-contacts-query.c
index 9639fae..e6baaf9 100644
--- a/gdata/services/contacts/gdata-contacts-query.c
+++ b/gdata/services/contacts/gdata-contacts-query.c
@@ -17,6 +17,19 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-contacts-query
+ * @short_description: GData Contacts query object
+ * @stability: Unstable
+ * @include: gdata/services/contacts/gdata-contacts-query.h
+ *
+ * #GDataContactsQuery represents a collection of query parameters specific to the Google Contacts service, which go above and beyond
+ * those catered for by #GDataQuery.
+ *
+ * For more information on the custom GData query parameters supported by #GDataContactsQuery, see the <ulink type="http"
+ * url="http://code.google.com/apis/contacts/docs/2.0/reference.html#Parameters";>online documentation</ulink>.
+ **/
+
 #include <config.h>
 #include <glib.h>
 #include <glib/gi18n-lib.h>
@@ -60,24 +73,50 @@ gdata_contacts_query_class_init (GDataContactsQueryClass *klass)
 	gobject_class->get_property = gdata_contacts_query_get_property;
 	gobject_class->finalize = gdata_contacts_query_finalize;
 
+	/**
+	 * GDataContactsQuery:order-by:
+	 *
+	 * Sorting criterion. The only supported value is <literal>lastmodified</literal>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_ORDER_BY,
 				g_param_spec_string ("order-by",
-					"Order by", "TODO",
+					"Order by", "Sorting criterion.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataContactsQuery:show-deleted:
+	 *
+	 * Whether to include deleted contacts in the query feed. Deleted contacts return %TRUE
+	 * from gdata_contacts_contact_is_deleted(), and have no other information. They do not
+	 * normally appear in query results.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_SHOW_DELETED,
 				g_param_spec_boolean ("show-deleted",
-					"Show deleted", "TODO",
+					"Show deleted?", "Whether to include deleted contacts in the query feed.",
 					FALSE,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataContactsQuery:sort-order:
+	 *
+	 * Sorting order direction. Can be either <literal>ascending</literal> or <literal>descending</literal>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_SORT_ORDER,
 				g_param_spec_string ("sort-order",
-					"Sort order", "TODO",
+					"Sort order", "Sorting order direction.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataContactsQuery:group:
+	 *
+	 * Constrains the results to only the contacts belonging to the group specified. The value of this parameter
+	 * should be a group ID URI.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_GROUP,
 				g_param_spec_string ("group",
-					"Group", "TODO",
+					"Group", "Constrains the results to only the contacts belonging to the group specified.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 }
@@ -151,22 +190,49 @@ gdata_contacts_query_set_property (GObject *object, guint property_id, const GVa
 	}
 }
 
+/**
+ * gdata_contacts_query_new:
+ * @q: a query string
+ *
+ * Creates a new #GDataContactsQuery with its #GDataQuery:q property set to @q.
+ *
+ * Return value: a new #GDataContactsQuery
+ **/
 GDataContactsQuery *
 gdata_contacts_query_new (const gchar *q)
 {
 	return g_object_new (GDATA_TYPE_CONTACTS_QUERY, "q", q, NULL);
 }
 
+/**
+ * gdata_contacts_query_new_with_limits:
+ * @q: a query string
+ * @start_index: a one-based start index for the results
+ * @max_results: the maximum number of results to return
+ *
+ * Creates a new #GDataContactsQuery with its #GDataQuery:q property set to @q, and the limits @start_index and @max_results
+ * applied.
+ *
+ * Return value: a new #GDataContactsQuery
+ **/
 GDataContactsQuery *
-gdata_contacts_query_new_with_limits (const gchar *q, GTimeVal *start_min, GTimeVal *start_max)
+gdata_contacts_query_new_with_limits (const gchar *q, gint start_index, gint max_results)
 {
 	return g_object_new (GDATA_TYPE_CONTACTS_QUERY,
 			     "q", q,
-			     "start-min", start_min,
-			     "start-max", start_max,
+			     "start-index", start_index,
+			     "max-results", max_results,
 			     NULL);
 }
 
+/**
+ * gdata_contacts_query_get_order_by:
+ * @self: a #GDataContactsQuery
+ *
+ * Gets the #GDataContactsQuery:order-by property.
+ *
+ * Return value: the order by property, or %NULL if it is unset
+ **/
 const gchar *
 gdata_contacts_query_get_order_by (GDataContactsQuery *self)
 {
@@ -174,6 +240,15 @@ gdata_contacts_query_get_order_by (GDataContactsQuery *self)
 	return self->priv->order_by;
 }
 
+/**
+ * gdata_contacts_query_set_order_by:
+ * @self: a #GDataContactsQuery
+ * @order_by: a new order by string, or %NULL
+ *
+ * Sets the #GDataContactsQuery:order-by property of the #GDataContactsQuery to the new order by string, @order_by.
+ *
+ * Set @order_by to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_contacts_query_set_order_by (GDataContactsQuery *self, const gchar *order_by)
 {
@@ -184,6 +259,14 @@ gdata_contacts_query_set_order_by (GDataContactsQuery *self, const gchar *order_
 	g_object_notify (G_OBJECT (self), "order-by");
 }
 
+/**
+ * gdata_contacts_query_show_deleted:
+ * @self: a #GDataContactsQuery
+ *
+ * Gets the #GDataContactsQuery:show-deleted property.
+ *
+ * Return value: %TRUE if deleted contacts should be shown, %FALSE otherwise
+ **/
 gboolean
 gdata_contacts_query_show_deleted (GDataContactsQuery *self)
 {
@@ -191,6 +274,13 @@ gdata_contacts_query_show_deleted (GDataContactsQuery *self)
 	return self->priv->show_deleted;
 }
 
+/**
+ * gdata_contacts_query_set_show_deleted:
+ * @self: a #GDataContactsQuery
+ * @show_deleted: %TRUE to show deleted contacts, %FALSE otherwise
+ *
+ * Sets the #GDataContactsQuery:show-deleted property of the #GDataContactsQuery.
+ **/
 void
 gdata_contacts_query_set_show_deleted (GDataContactsQuery *self, gboolean show_deleted)
 {
@@ -199,6 +289,14 @@ gdata_contacts_query_set_show_deleted (GDataContactsQuery *self, gboolean show_d
 	g_object_notify (G_OBJECT (self), "show-deleted");
 }
 
+/**
+ * gdata_contacts_query_get_sort_order:
+ * @self: a #GDataContactsQuery
+ *
+ * Gets the #GDataContactsQuery:sort-order property.
+ *
+ * Return value: the sort order property, or %NULL if it is unset
+ **/
 const gchar *
 gdata_contacts_query_get_sort_order (GDataContactsQuery *self)
 {
@@ -206,6 +304,15 @@ gdata_contacts_query_get_sort_order (GDataContactsQuery *self)
 	return self->priv->sort_order;
 }
 
+/**
+ * gdata_contacts_query_set_sort_order:
+ * @self: a #GDataContactsQuery
+ * @sort_order: a new sort order string, or %NULL
+ *
+ * Sets the #GDataContactsQuery:sort-order property of the #GDataContactsQuery to the new sort order string, @sort_order.
+ *
+ * Set @sort_order to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_contacts_query_set_sort_order (GDataContactsQuery *self, const gchar *sort_order)
 {
@@ -216,6 +323,14 @@ gdata_contacts_query_set_sort_order (GDataContactsQuery *self, const gchar *sort
 	g_object_notify (G_OBJECT (self), "sort-order");
 }
 
+/**
+ * gdata_contacts_query_get_group:
+ * @self: a #GDataContactsQuery
+ *
+ * Gets the #GDataContactsQuery:group property.
+ *
+ * Return value: the group property, or %NULL if it is unset
+ **/
 const gchar *
 gdata_contacts_query_get_group (GDataContactsQuery *self)
 {
@@ -223,6 +338,15 @@ gdata_contacts_query_get_group (GDataContactsQuery *self)
 	return self->priv->group;
 }
 
+/**
+ * gdata_contacts_query_set_group:
+ * @self: a #GDataContactsQuery
+ * @group: a new group ID URI, or %NULL
+ *
+ * Sets the #GDataContactsQuery:group property of the #GDataContactsQuery to the new group ID URI, @group.
+ *
+ * Set @group to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_contacts_query_set_group (GDataContactsQuery *self, const gchar *group)
 {
diff --git a/gdata/services/contacts/gdata-contacts-query.h b/gdata/services/contacts/gdata-contacts-query.h
index 2cd7c69..0959a5a 100644
--- a/gdata/services/contacts/gdata-contacts-query.h
+++ b/gdata/services/contacts/gdata-contacts-query.h
@@ -36,19 +36,30 @@ G_BEGIN_DECLS
 
 typedef struct _GDataContactsQueryPrivate	GDataContactsQueryPrivate;
 
+/**
+ * GDataContactsQuery:
+ *
+ * All the fields in the #GDataContactsQuery structure are private and should never be accessed directly.
+ **/
 typedef struct {
 	GDataQuery parent;
 	GDataContactsQueryPrivate *priv;
 } GDataContactsQuery;
 
+/**
+ * GDataContactsQueryClass:
+ *
+ * All the fields in the #GDataContactsQueryClass structure are private and should never be accessed directly.
+ **/
 typedef struct {
+	/*< private >*/
 	GDataQueryClass parent;
 } GDataContactsQueryClass;
 
 GType gdata_contacts_query_get_type (void);
 
 GDataContactsQuery *gdata_contacts_query_new (const gchar *q);
-GDataContactsQuery *gdata_contacts_query_new_with_limits (const gchar *q, GTimeVal *start_min, GTimeVal *start_max);
+GDataContactsQuery *gdata_contacts_query_new_with_limits (const gchar *q, gint start_index, gint max_results);
 
 const gchar *gdata_contacts_query_get_order_by (GDataContactsQuery *self);
 void gdata_contacts_query_set_order_by (GDataContactsQuery *self, const gchar *order_by);
diff --git a/gdata/services/contacts/gdata-contacts-service.c b/gdata/services/contacts/gdata-contacts-service.c
index cdb62b3..f48d8db 100644
--- a/gdata/services/contacts/gdata-contacts-service.c
+++ b/gdata/services/contacts/gdata-contacts-service.c
@@ -17,6 +17,19 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-contacts-service
+ * @short_description: GData Contacts service object
+ * @stability: Unstable
+ * @include: gdata/services/contacts/gdata-contacts-service.h
+ *
+ * #GDataContactsService is a subclass of #GDataService for communicating with the GData API of Google Contacts. It supports querying
+ * for, inserting, editing and deleting contacts from a Google address book.
+ *
+ * For more details of Google Contacts' GData API, see the <ulink type="http" url="http://code.google.com/apis/contacts/docs/2.0/reference.html";>
+ * online documentation</ulink>.
+ **/
+
 #include <config.h>
 #include <glib.h>
 #include <glib/gi18n-lib.h>
@@ -46,6 +59,14 @@ gdata_contacts_service_init (GDataContactsService *self)
 	/* Nothing to see here */
 }
 
+/**
+ * gdata_contacts_service_new:
+ * @client_id: your application's client ID
+ *
+ * Creates a new #GDataContactsService. The @client_id must be unique for your application, and as registered with Google.
+ *
+ * Return value: a new #GDataContactsService, or %NULL
+ **/
 GDataContactsService *
 gdata_contacts_service_new (const gchar *client_id)
 {
@@ -56,6 +77,21 @@ gdata_contacts_service_new (const gchar *client_id)
 			     NULL);
 }
 
+/**
+ * gdata_contacts_service_query_contacts:
+ * @self: a #GDataContactsService
+ * @query: a #GDataContactsQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @error: a #GError, or %NULL
+ *
+ * Queries the service to return a list of contacts matching the given @query.
+ *
+ * For more details, see gdata_service_query().
+ *
+ * Return value: a #GDataFeed of query results; unref with g_object_unref()
+ **/
 GDataFeed *
 gdata_contacts_service_query_contacts (GDataContactsService *self, GDataContactsQuery *query, GCancellable *cancellable,
 				       GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error)
@@ -71,6 +107,22 @@ gdata_contacts_service_query_contacts (GDataContactsService *self, GDataContacts
 				    GDATA_TYPE_CONTACTS_CONTACT, cancellable, progress_callback, progress_user_data, error);
 }
 
+/**
+ * gdata_contacts_service_query_contacts_async:
+ * @self: a #GDataContactsService
+ * @query: a #GDataContactsQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @callback: a #GAsyncReadyCallback to call when authentication is finished
+ * @user_data: data to pass to the @callback function
+ *
+ * Queries the service to return a list of contacts matching the given @query. @self and
+ * @query are all reffed when this function is called, so can safely be unreffed after this function returns.
+ *
+ * For more details, see gdata_contacts_service_query_contacts(), which is the synchronous version of this function,
+ * and gdata_service_query_async(), which is the base asynchronous query function.
+ **/
 void
 gdata_contacts_service_query_contacts_async (GDataContactsService *self, GDataContactsQuery *query, GCancellable *cancellable,
 					     GDataQueryProgressCallback progress_callback, gpointer progress_user_data,
@@ -88,10 +140,23 @@ gdata_contacts_service_query_contacts_async (GDataContactsService *self, GDataCo
 				   GDATA_TYPE_CONTACTS_CONTACT, cancellable, progress_callback, progress_user_data, callback, user_data);
 }
 
-/* TODO: Async variant */
+/**
+ * gdata_contacts_service_insert_contact:
+ * @self: a #GDataContactsService
+ * @contact: the #GDataContactsContact to insert
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Inserts @contact by uploading it to the online contacts service.
+ *
+ * For more details, see gdata_service_insert_entry().
+ *
+ * Return value: an updated #GDataContactsContact, or %NULL
+ **/
 GDataContactsContact *
 gdata_contacts_service_insert_contact (GDataContactsService *self, GDataContactsContact *contact, GCancellable *cancellable, GError **error)
 {
+	/* TODO: Async variant */
 	gchar *uri;
 	GDataEntry *entry;
 
diff --git a/gdata/services/contacts/gdata-contacts-service.h b/gdata/services/contacts/gdata-contacts-service.h
index 1bb143d..c78774d 100644
--- a/gdata/services/contacts/gdata-contacts-service.h
+++ b/gdata/services/contacts/gdata-contacts-service.h
@@ -38,11 +38,22 @@ G_BEGIN_DECLS
 
 typedef struct _GDataContactsServicePrivate	GDataContactsServicePrivate;
 
+/**
+ * GDataContactsService:
+ *
+ * All the fields in the #GDataContactsService structure are private and should never be accessed directly.
+ **/
 typedef struct {
 	GDataService parent;
 } GDataContactsService;
 
+/**
+ * GDataContactsServiceClass:
+ *
+ * All the fields in the #GDataContactsServiceClass structure are private and should never be accessed directly.
+ **/
 typedef struct {
+	/*< private >*/
 	GDataServiceClass parent;
 } GDataContactsServiceClass;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]