[libgdata] Bug 656973 â Add an example of starring a document

[Philip Withnall <pwithnall src gnome org>]

commit 41129e8ac50e22dddbc5eaf26604e74785f81810
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Oct 10 23:17:35 2011 +0100

    Bug 656973 â Add an example of starring a document
    
    Add an example of starring a document to the GDataDocumentsService
    documentation.
    
    This adds the following new API (for convenience of referring to URIs):
     â GDATA_CATEGORY_SCHEMA_LABELS
     â GDATA_CATEGORY_SCHEMA_LABELS_STARRED
    
    Closes: bgo#656973

 docs/reference/gdata-sections.txt                  |    2 +
 gdata/atom/gdata-category.h                        |   20 ++++++++++
 gdata/services/documents/gdata-documents-service.c |   40 ++++++++++++++++++++
 3 files changed, 62 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index 4411ffa..049422b 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -756,6 +756,8 @@ GDataCalendarFeedPrivate
 <SECTION>
 <FILE>gdata-category</FILE>
 <TITLE>GDataCategory</TITLE>
+GDATA_CATEGORY_SCHEMA_LABELS
+GDATA_CATEGORY_SCHEMA_LABELS_STARRED
 GDataCategory
 GDataCategoryClass
 gdata_category_new
diff --git a/gdata/atom/gdata-category.h b/gdata/atom/gdata-category.h
index bae452f..cc6f862 100644
--- a/gdata/atom/gdata-category.h
+++ b/gdata/atom/gdata-category.h
@@ -27,6 +27,26 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GDATA_CATEGORY_SCHEMA_LABELS:
+ *
+ * A schema for categories which label the entry they're applied to in some way, such as starring it. The semantics of the various labels
+ * (such as %GDATA_CATEGORY_SCHEMA_LABELS_STARRED) are service-specific.
+ *
+ * Since: 0.11.0
+ */
+#define GDATA_CATEGORY_SCHEMA_LABELS "http://schemas.google.com/g/2005/labels";
+
+/**
+ * GDATA_CATEGORY_SCHEMA_LABELS_STARRED:
+ *
+ * A term for categories of the %GDATA_CATEGORY_SCHEMA_LABELS schema which labels an entry as being âstarredâ. The semantics of this label are
+ * service-specific, but are obvious for services such as Google Documents.
+ *
+ * Since: 0.11.0
+ */
+#define GDATA_CATEGORY_SCHEMA_LABELS_STARRED GDATA_CATEGORY_SCHEMA_LABELS"#starred"
+
 #define GDATA_TYPE_CATEGORY		(gdata_category_get_type ())
 #define GDATA_CATEGORY(o)		(G_TYPE_CHECK_INSTANCE_CAST ((o), GDATA_TYPE_CATEGORY, GDataCategory))
 #define GDATA_CATEGORY_CLASS(k)		(G_TYPE_CHECK_CLASS_CAST((k), GDATA_TYPE_CATEGORY, GDataCategoryClass))
diff --git a/gdata/services/documents/gdata-documents-service.c b/gdata/services/documents/gdata-documents-service.c
index 252d7e6..21dbe15 100644
--- a/gdata/services/documents/gdata-documents-service.c
+++ b/gdata/services/documents/gdata-documents-service.c
@@ -205,6 +205,46 @@
  * 	</programlisting>
  * </example>
  *
+ * Starred documents are denoted by being in the %GDATA_CATEGORY_SCHEMA_LABELS_STARRED category of the %GDATA_CATEGORY_SCHEMA_LABELS schema. Documents
+ * can be starred or unstarred simply by adding or removing this category from them and updating the document:
+ *
+ * <example>
+ * 	<title>Starring a Document</title>
+ * 	<programlisting>
+ *	GDataDocumentsService *service;
+ *	GDataDocumentsEntry *document, *updated_document;
+ *	GDataCategory *starred_category;
+ *	GError *error = NULL;
+ *
+ *	/<!-- -->* Create a service and retrieve the document to be starred *<!-- -->/
+ *	service = create_documents_service ();
+ *	document = get_document_to_be_starred (service);
+ *
+ *	/<!-- -->* Add the âstarredâ category to the document *<!-- -->/
+ *	starred_category = gdata_category_new (GDATA_CATEGORY_SCHEMA_LABELS_STARRED, GDATA_CATEGORY_SCHEMA_LABELS, "starred");
+ *	gdata_entry_add_category (GDATA_ENTRY (document), starred_category);
+ *	g_object_unref (starred_category);
+ *
+ *	/<!-- -->* Propagate the updated document to the server *<!-- -->/
+ *	updated_document = GDATA_DOCUMENTS_ENTRY (gdata_service_update_entry (GDATA_SERVICE (service),
+ *	                                                                      gdata_documents_service_get_primary_authorization_domain (),
+ *	                                                                      GDATA_ENTRY (document), NULL, &error));
+ *
+ *	g_object_unref (document);
+ *	g_object_unref (service);
+ *
+ *	if (error != NULL) {
+ *		g_error ("Error starring document: %s", error->message);
+ *		g_error_free (error);
+ *		return;
+ *	}
+ *
+ *	/<!-- -->* Do something with the newly-starred document, like update it in the UI *<!-- -->/
+ *
+ *	g_object_unref (updated_document);
+ * 	</programlisting>
+ * </example>
+ *
  * Since: 0.4.0
  **/