[libgdata] Bug 579885 — Add code examples to documentation

[Philip Withnall <pwithnall src gnome org>]

commit 4e45d2f1cf199f9eed524769a6344b4dab25d546
Author: Richard Schwarting <aquarichy gmail com>
Date:   Sun May 2 17:44:20 2010 +0100

    Bug 579885 â?? Add code examples to documentation
    
    Add code examples to the documentation for GDataPicasaWebAlbum,
    GDataPicasaWebFile and GDataPicasaWebService. Helps: bgo#579885

 gdata/services/picasaweb/gdata-picasaweb-album.c   |   54 +++++++++++++++++++-
 gdata/services/picasaweb/gdata-picasaweb-file.c    |   50 ++++++++++++++++++-
 gdata/services/picasaweb/gdata-picasaweb-service.c |   51 ++++++++++++++++++
 3 files changed, 152 insertions(+), 3 deletions(-)
---
diff --git a/gdata/services/picasaweb/gdata-picasaweb-album.c b/gdata/services/picasaweb/gdata-picasaweb-album.c
index 3bdd2cc..610c6d3 100644
--- a/gdata/services/picasaweb/gdata-picasaweb-album.c
+++ b/gdata/services/picasaweb/gdata-picasaweb-album.c
@@ -29,6 +29,53 @@
  * For more details of Google PicasaWeb's GData API, see the <ulink type="http" url="http://code.google.com/apis/picasaweb/reference.html";>
  * online documentation</ulink>.
  *
+ * <example>
+ * 	<title>Getting Basic Album Data</title>
+ * 	<programlisting>
+ *	GDataFeed *album_feed;
+ *	GList *album_entries;
+ *
+ *	/<!-- -->* Query for a feed of GDataPicasaWebAlbum<!-- -->s owned by user "libgdata.picasaweb" *<!-- -->/
+ *	album_feed = gdata_picasaweb_service_query_all_albums (service, NULL, "libgdata.picasaweb", NULL, NULL, NULL, NULL);
+ *
+ *	/<!-- -->* Get a list of GDataPicasaWebAlbum<!-- -->s from the query's feed *<!-- -->/
+ *	for (album_entries = gdata_feed_get_entries (album_feed); album_entries != NULL; album_entries = album_entries->next) {
+ *		GDataPicasaWebAlbum *album;
+ *		guint num_photos;
+ *		const gchar *owner_nickname, *title, *summary;
+ *		GTimeVal timeval;
+ *		GList *thumbnails;
+ *
+ *		album = GDATA_PICASAWEB_ALBUM (album_entries->data);
+ *
+ *		/<!-- -->* Get various bits of information about the album *<!-- -->/
+ *		num_photos = gdata_picasaweb_album_get_num_photos (album);
+ *		owner_nickname = gdata_picasaweb_album_get_nickname (album);
+ *		title = gdata_entry_get_title (GDATA_ENTRY (album));
+ *		summary = gdata_entry_get_summary (GDATA_ENTRY (album));
+ *		/<!-- -->* Get the day the album was shot on or, if not set, when it was uploaded *<!-- -->/
+ *		gdata_picasaweb_album_get_timestamp (album, &timeval);
+ *
+ *		for (thumbnails = gdata_picasaweb_album_get_thumbnails (album); thumbnails != NULL; thumbnails = thumbnails->next) {
+ *			GDataMediaThumbnail *thumbnail;
+ *			GFile *new_file;
+ *
+ *			thumbnail = GDATA_MEDIA_THUMBNAIL (thumbnails->data);
+ *			/<!-- -->* Do something fun with the thumbnails, like download and display them.
+ *			 * Note that this is a blocking operation. *<!-- -->/
+ *			new_file = gdata_media_thumbnail_download (thumbnail, GDATA_SERVICE (service), default_filename, target_file, FALSE,
+ *			                                           NULL, NULL);
+ *			/<!-- -->* ... *<!-- -->/
+ *			g_object_unref (new_file);
+ *		}
+ *
+ *		/<!-- -->* Do something worthwhile with your album data *<!-- -->/
+ *	}
+ *
+ *	g_object_unref (album_feed);
+ * 	</programlisting>
+ * </example>
+ *
  * Since: 0.4.0
  **/
 
@@ -943,8 +990,11 @@ gdata_picasaweb_album_set_visibility (GDataPicasaWebAlbum *self, GDataPicasaWebV
  * @self: a #GDataPicasaWebAlbum
  * @timestamp: a #GTimeVal
  *
- * Gets the #GDataPicasaWebAlbum:timestamp property and puts it in @timestamp. If the property is unset,
- * both fields in the #GTimeVal will be set to <code class="literal">0</code>.
+ * Gets the #GDataPicasaWebAlbum:timestamp property and puts it in
+ * @timestamp. This value usually holds either the date that best
+ * corresponds to the album of photos, or to the day it was uploaded.
+ * If the property is unset, both fields in the #GTimeVal will be set
+ * to <code class="literal">0</code>.
  *
  * Since: 0.4.0
  **/
diff --git a/gdata/services/picasaweb/gdata-picasaweb-file.c b/gdata/services/picasaweb/gdata-picasaweb-file.c
index 661bb2a..db40ed6 100644
--- a/gdata/services/picasaweb/gdata-picasaweb-file.c
+++ b/gdata/services/picasaweb/gdata-picasaweb-file.c
@@ -24,11 +24,59 @@
  * @stability: Unstable
  * @include: gdata/services/picasaweb/gdata-picasaweb-file.h
  *
- * #GDataPicasaWebFile is a subclass of #GDataEntry to represent a file in an album on Google PicasaWeb.
+ * #GDataPicasaWebFile is a subclass of #GDataEntry to represent a file (photo or video) in an album on Google PicasaWeb.
  *
  * For more details of Google PicasaWeb's GData API, see the
  * <ulink type="http" url="http://code.google.com/apis/picasaweb/developers_guide_protocol.html";>online documentation</ulink>.
  *
+ * <example>
+ *	<title>Getting Basic Photo Data</title>
+ *	<programlisting>
+ *	GDataFeed *photo_feed;
+ *	GList *photo_entries;
+ *
+ *	/<!-- -->* Query for a feed of GDataPicasaWebFile<!-- -->s belonging to the given GDataPicasaWebAlbum album *<!-- -->/
+ *	photo_feed = gdata_picasaweb_service_query_files (service, album, NULL, NULL, NULL, NULL, NULL);
+ *
+ *	/<!-- -->* Get a list of GDataPicasaWebFile<!-- -->s from the query's feed *<!-- -->/
+ *	for (photo_entries = gdata_feed_get_entries (photo_feed); photo_entries != NULL; photo_entries = photo_entries->next) {
+ *		GDataPicasaWebFile *photo;
+ *		guint height, width;
+ *		gsize file_size;
+ *		GTimeVal timestamp;
+ *		const gchar *title, *summary;
+ *		GList *contents;
+ *
+ *		photo = GDATA_PICASAWEB_FILE (photo_entries->data);
+ *
+ *		/<!-- -->* Get various bits of information about the photo *<!-- -->/
+ *		height = gdata_picasaweb_file_get_height (photo);
+ *		width = gdata_picasaweb_file_get_width (photo);
+ *		file_size = gdata_picasaweb_file_get_size (photo);
+ *		gdata_picasaweb_file_get_timestamp (photo, &timestamp);
+ *		title = gdata_entry_get_title (GDATA_ENTRY (photo));
+ *		summary = gdata_entry_get_summary (GDATA_ENTRY (photo));
+ *
+ *		/<!-- -->* Obtain the image data at various sizes *<!-- -->/
+ *		for (contents = gdata_picasaweb_file_get_contents (photo); contents != NULL; contents = contents->next) {
+ *			GDataMediaContent *content;
+ *			GFile *new_file;
+ *
+ *			content = GDATA_MEDIA_CONTENT (contents->data);
+ *			/<!-- -->* Do something fun with the actual images, like download and display them.
+ *			 * Note that this is a blocking operation. *<!-- -->/
+ *			new_file = gdata_media_content_download (content, GDATA_SERVICE (service), default_filename, target_file, FALSE, NULL, NULL);
+ *			/<!-- -->* ... *<!-- -->/
+ *			g_object_unref (new_file);
+ *		}
+ *
+ *		/<!-- -->* Do something worthwhile with your image data *<!-- -->/
+ *	}
+ *
+ *	g_object_unref (photo_feed);
+ *	</programlisting>
+ * </example>
+ *
  * Since: 0.4.0
  **/
 
diff --git a/gdata/services/picasaweb/gdata-picasaweb-service.c b/gdata/services/picasaweb/gdata-picasaweb-service.c
index 0f3e4f8..24dffaf 100644
--- a/gdata/services/picasaweb/gdata-picasaweb-service.c
+++ b/gdata/services/picasaweb/gdata-picasaweb-service.c
@@ -30,6 +30,55 @@
  * For more details of PicasaWeb's GData API, see the <ulink type="http" url="http://code.google.com/apis/picasaweb/developers_guide_protocol.html";>
  * online documentation</ulink>.
  *
+ * <example>
+ * 	<title>Authenticating and Creating a New Album</title>
+ * 	<programlisting>
+ *	GDataPicasaWebService *service;
+ *	GDataPicasaWebAlbum *album, *inserted_album;
+ *
+ *	/<!-- -->* Create a service object and authenticate with the PicasaWeb server *<!-- -->/
+ *	service = gdata_picasaweb_service_new ("companyName-applicationName-versionID");
+ *	gdata_service_authenticate (GDATA_SERVICE (service), username, password, NULL, NULL);
+ *
+ *	/<!-- -->* Create a GDataPicasaWebAlbum entry for the new album, setting some information about it *<!-- -->/
+ *	album = gdata_picasaweb_album_new (NULL);
+ *	gdata_entry_set_title (GDATA_ENTRY (album), "Photos from the Rhine");
+ *	gdata_entry_set_summary (GDATA_ENTRY (album), "An album of our adventures on the great river.");
+ *	gdata_picasaweb_album_set_location (album, "The Rhine, Germany");
+ *
+ *	/<!-- -->* Insert the new album on the server. Note that this is a blocking operation. *<!-- -->/
+ *	inserted_album = gdata_picasaweb_service_insert_album (service, album, NULL, NULL);
+ *
+ *	g_object_unref (album);
+ *	g_object_unref (inserted_album);
+ *	g_object_unref (service);
+ *	</programlisting>
+ * </example>
+ *
+ * <example>
+ * 	<title>Uploading a Photo or Video</title>
+ * 	<programlisting>
+ *	GDataPicasaWebFile *file_entry, *uploaded_file_entry;
+ *	GFile *file_data;
+ *
+ *	/<!-- -->* Specify the GFile image on disk to upload *<!-- -->/
+ *	file_data = g_file_new_for_path (path);
+ *
+ *	/<!-- -->* Create a GDataPicasaWebFile entry for the image, setting a title and caption/summary *<!-- -->/
+ *	file_entry = gdata_picasaweb_file_new (NULL);
+ *	gdata_entry_set_title (GDATA_ENTRY (file_entry), "Black Cat");
+ *	gdata_entry_set_summary (GDATA_ENTRY (file_entry), "Photo of the world's most beautiful cat.");
+ *
+ *	/<!-- -->* Upload the file to the server. Note that this is a blocking operation. *<!-- -->/
+ *	uploaded_file_entry = gdata_picasaweb_service_upload_file (service, album, file_entry, file_data, NULL, NULL);
+ *
+ *	g_object_unref (file_entry);
+ *	g_object_unref (uploaded_file_entry);
+ *	g_object_unref (file_data);
+ * 	</programlisting>
+ * </example>
+ *
+ *
  * Since: 0.4.0
  **/
 
@@ -66,6 +115,8 @@ gdata_picasaweb_service_init (GDataPicasaWebService *self)
  * @client_id: your application's client ID
  *
  * Creates a new #GDataPicasaWebService. The @client_id must be unique for your application, and as registered with Google.
+ * The <ulink type="http" url="http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html#Request";>recommended
+ * form</ulink> is "companyName-applicationName-versionID".
  *
  * Return value: a new #GDataPicasaWebService, or %NULL
  *