[libgdata] docs: Add an example of inserting an access rule into an ACL

[Philip Withnall <pwithnall src gnome org>]

commit 3c8bb54c96216ecfd684184260a516d47dc202bd
Author: Philip Withnall <philip tecnocode co uk>
Date:   Fri Aug 24 18:51:37 2012 +0100

    docs: Add an example of inserting an access rule into an ACL
    
    Hopefully this should make ACLs a little less opaque.

 gdata/gdata-access-handler.c |    2 ++
 gdata/gdata-access-rule.c    |   42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 0 deletions(-)
---
diff --git a/gdata/gdata-access-handler.c b/gdata/gdata-access-handler.c
index 5203bc3..0093f61 100644
--- a/gdata/gdata-access-handler.c
+++ b/gdata/gdata-access-handler.c
@@ -27,6 +27,8 @@
  * access control list (ACL). It has a set of methods which allow the #GDataAccessRule<!-- -->s for the access handler/entry to be retrieved,
  * added, modified and deleted, with immediate effect.
  *
+ * For an example of inserting an access rule into an ACL, see the documentation for #GDataAccessRule.
+ *
  * When implementing the interface, classes must implement an <function>is_owner_rule</function> function. It's optional to implement a
  * <function>get_authorization_domain</function> function, but if it's not implemented, any operations on the access handler's
  * #GDataAccessRule<!-- -->s will be performed unauthorized (i.e. as if by a non-logged-in user). This will not usually work.
diff --git a/gdata/gdata-access-rule.c b/gdata/gdata-access-rule.c
index f9a898d..51409ac 100644
--- a/gdata/gdata-access-rule.c
+++ b/gdata/gdata-access-rule.c
@@ -30,6 +30,48 @@
  * Access rules should be inserted to the %GDATA_LINK_ACCESS_CONTROL_LIST URI of the feed or entry they should be applied to. This will return a
  * %GDATA_SERVICE_ERROR_CONFLICT error if a rule already exists on that feed or entry for that scope type and value.
  *
+ * <example>
+ * 	<title>Adding a Rule to the Access Control List for an Entry</title>
+ * 	<programlisting>
+ *	GDataService *service;
+ *	GDataEntry *entry;
+ *	GDataFeed *acl_feed;
+ *	GDataAccessRule *rule, *new_rule;
+ *	GError *error = NULL;
+ *
+ *	/<!-- -->* Retrieve a GDataEntry which will have a new rule inserted into its ACL. *<!-- -->/
+ *	service = build_my_service ();
+ *	entry = get_the_entry (service);
+ *
+ *	/<!-- -->* Create and insert a new access rule for example gmail com which grants them _no_ permissions on the entry.
+ *	 * In a real application, the GDataEntry subclass would define its own access roles which are more useful. For example,
+ *	 * GDataDocumentsEntry defines access roles for users who can read (but not write) a Google Document, and users who
+ *	 * can also write to the document. *<!-- -->/
+ *	rule = gdata_access_rule_new (NULL);
+ *	gdata_access_rule_set_role (rule, GDATA_ACCESS_ROLE_NONE); /<!-- -->* or, for example, GDATA_DOCUMENTS_ACCESS_ROLE_READER *<!-- -->/
+ *	gdata_access_rule_set_scope (rule, GDATA_ACCESS_SCOPE_USER, "example gmail com"); /<!-- -->* e-mail address of the user the ACL applies to *<!-- -->/
+ *
+ *	acl_link = gdata_entry_look_up_link (entry, GDATA_LINK_ACCESS_CONTROL_LIST);
+ *	new_rule = GDATA_ACCESS_RULE (gdata_service_insert_entry (GDATA_SERVICE (service), gdata_link_get_uri (acl_link), GDATA_ENTRY (rule),
+ *	                                                          NULL, &error));
+ *	g_object_unref (acl_link);
+ *
+ *	g_object_unref (rule);
+ *	g_object_unref (entry);
+ *	g_object_unref (service);
+ *
+ *	if (error != NULL) {
+ *		g_error ("Error inserting access rule: %s", error->message);
+ *		g_error_free (error);
+ *		return;
+ *	}
+ *
+ *	/<!-- -->* Potentially do something with the new_rule here, such as store its ID for later use. *<!-- -->/
+ *
+ *	g_object_unref (new_rule);
+ * 	</programlisting>
+ * </example>
+ *
  * Since: 0.3.0
  **/