GNOME.org
 

[libgdata] Added API documentation for structs in the Media RSS and YouTube namespaces

commit e41798a2ce893817be1c5f8601c48c7abf9a600b
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Apr 23 07:36:57 2009 +0100

    Added API documentation for structs in the Media RSS and YouTube namespaces
---
 docs/reference/gdata-docs.xml          |    1 +
 docs/reference/gdata-sections.txt      |   34 +++++++++
 gdata/gdata-media-rss.c                |  128 +++++++++++++++++++++++++++++++-
 gdata/gdata-media-rss.h                |   91 ++++++++++++++++++++++-
 gdata/services/youtube/gdata-youtube.c |   27 +++++++-
 gdata/services/youtube/gdata-youtube.h |   12 +++
 6 files changed, 287 insertions(+), 6 deletions(-)

diff --git a/docs/reference/gdata-docs.xml b/docs/reference/gdata-docs.xml
index 3602c42..78856d7 100644
--- a/docs/reference/gdata-docs.xml
+++ b/docs/reference/gdata-docs.xml
@@ -23,6 +23,7 @@
 		<title>Namespace API</title>
 		<xi:include href="xml/gdata-atom.xml"/>
 		<xi:include href="xml/gdata-gdata.xml"/>
+		<xi:include href="xml/gdata-youtube.xml"/>
 	</chapter>
 
 	<chapter>
diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index 5c1cd00..80e1035 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -210,6 +210,32 @@ gdata_gd_who_free
 </SECTION>
 
 <SECTION>
+<FILE>gdata-media</FILE>
+<TITLE>Media RSS API</TITLE>
+GDataMediaCategory
+gdata_media_category_new
+gdata_media_category_free
+GDataMediaExpression
+GDataMediaContent
+gdata_media_content_new
+gdata_media_content_free
+GDataMediaCredit
+gdata_media_credit_new
+gdata_media_credit_free
+GDataMediaRating
+gdata_media_rating_new
+gdata_media_rating_free
+GDataMediaRestriction
+gdata_media_restriction_new
+gdata_media_restriction_free
+GDataMediaThumbnail
+gdata_media_thumbnail_new
+gdata_media_thumbnail_free
+gdata_media_thumbnail_parse_time
+gdata_media_thumbnail_build_time
+</SECTION>
+
+<SECTION>
 <FILE>gdata-youtube-service</FILE>
 <TITLE>GDataYouTubeService</TITLE>
 GDataYouTubeService
@@ -291,6 +317,14 @@ GDataYouTubeVideoPrivate
 </SECTION>
 
 <SECTION>
+<FILE>gdata-youtube</FILE>
+<TITLE>YouTube API</TITLE>
+GDataYouTubeState
+gdata_youtube_state_new
+gdata_youtube_state_free
+</SECTION>
+
+<SECTION>
 <FILE>gdata-contacts-service</FILE>
 <TITLE>GDataContactsService</TITLE>
 GDataContactsService
diff --git a/gdata/gdata-media-rss.c b/gdata/gdata-media-rss.c
index ff5db11..eebf8ad 100644
--- a/gdata/gdata-media-rss.c
+++ b/gdata/gdata-media-rss.c
@@ -25,6 +25,16 @@
 /* This may have been subverted by Google for the YouTube API, but it was actually originally
  * designed by Yahoo. Standards reference here: http://search.yahoo.com/mrss/ */
 
+/**
+ * gdata_media_rating_new:
+ * @country: a comma-delimited list of ISO 3166 country codes where the content is restricted
+ * @scheme: a URI identifying the rating scheme, or %NULL
+ *
+ * Creates a new #GDataMediaRating. More information is available in the <ulink type="http"
+ * url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink>.
+ *
+ * Return value: a new #GDataMediaRating
+ **/
 GDataMediaRating *
 gdata_media_rating_new (const gchar *scheme, const gchar *country)
 {
@@ -34,6 +44,12 @@ gdata_media_rating_new (const gchar *scheme, const gchar *country)
 	return self;
 }
 
+/**
+ * gdata_media_rating_free:
+ * @self: a #GDataMediaRating
+ *
+ * Frees a #GDataMediaRating.
+ **/
 void
 gdata_media_rating_free (GDataMediaRating *self)
 {
@@ -45,6 +61,16 @@ gdata_media_rating_free (GDataMediaRating *self)
 	g_slice_free (GDataMediaRating, self);
 }
 
+/**
+ * gdata_media_restriction_new:
+ * @countries: a space-delimited list of ISO 3166 country codes
+ * @relationship: %TRUE if the given @countries are not restricted regarding the content, %FALSE otherwise
+ *
+ * Creates a new #GDataMediaRestriction. More information is available in the <ulink type="http"
+ * url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink>.
+ *
+ * Return value: a new #GDataMediaRestriction
+ **/
 GDataMediaRestriction *
 gdata_media_restriction_new (const gchar *countries, gboolean relationship)
 {
@@ -54,6 +80,12 @@ gdata_media_restriction_new (const gchar *countries, gboolean relationship)
 	return self;
 }
 
+/**
+ * gdata_media_restriction_free:
+ * @self: a #GDataMediaRestriction
+ *
+ * Frees a #GDataMediaRestriction.
+ **/
 void
 gdata_media_restriction_free (GDataMediaRestriction *self)
 {
@@ -64,6 +96,17 @@ gdata_media_restriction_free (GDataMediaRestriction *self)
 	g_slice_free (GDataMediaRestriction, self);
 }
 
+/**
+ * gdata_media_category_new:
+ * @category: a category describing the content
+ * @scheme: a URI identifying the categorisation scheme, or %NULL
+ * @label: a human-readable name for the category, or %NULL
+ *
+ * Creates a new #GDataMediaCategory. More information is available in the <ulink type="http"
+ * url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink>.
+ *
+ * Return value: a new #GDataMediaCategory
+ **/
 GDataMediaCategory *
 gdata_media_category_new (const gchar *category, const gchar *label, const gchar *scheme)
 {
@@ -74,6 +117,12 @@ gdata_media_category_new (const gchar *category, const gchar *label, const gchar
 	return self;
 }
 
+/**
+ * gdata_media_category_free:
+ * @self: a #GDataMediaCategory
+ *
+ * Frees a #GDataMediaCategory.
+ **/
 void
 gdata_media_category_free (GDataMediaCategory *self)
 {
@@ -86,6 +135,16 @@ gdata_media_category_free (GDataMediaCategory *self)
 	g_slice_free (GDataMediaCategory, self);
 }
 
+/**
+ * gdata_media_credit_new:
+ * @credit: the username of someone who contributed towards the media
+ * @partner: %TRUE if the video was uploaded by a YouTube partner, %FALSE otherwise
+ *
+ * Creates a new #GDataMediaCredit. More information is available in the <ulink type="http"
+ * url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink>.
+ *
+ * Return value: a new #GDataMediaCredit
+ **/
 GDataMediaCredit *
 gdata_media_credit_new (const gchar *credit, gboolean partner)
 {
@@ -95,6 +154,12 @@ gdata_media_credit_new (const gchar *credit, gboolean partner)
 	return self;
 }
 
+/**
+ * gdata_media_credit_free:
+ * @self: a #GDataMediaCredit
+ *
+ * Frees a #GDataMediaCredit.
+ **/
 void
 gdata_media_credit_free (GDataMediaCredit *self)
 {
@@ -105,6 +170,21 @@ gdata_media_credit_free (GDataMediaCredit *self)
 	g_slice_free (GDataMediaCredit, self);
 }
 
+/**
+ * gdata_media_content_new:
+ * @uri: the media object's URI
+ * @type: the media object's MIME type, or %NULL
+ * @is_default: %TRUE if this is the default object for the media group, %FALSE otherwise
+ * @expression: whether this media is a full version or just a sample
+ * @duration: the length of the media, in seconds, or %-1
+ * @format: the video format of the media (see the <ulink type="http"
+ * url="http://code.google.com/apis/youtube/2.0/reference.html#youtube_data_api_tag_media:content";>YouTube specification</ulink>)
+ *
+ * Creates a new #GDataMediaContent. More information is available in the <ulink type="http"
+ * url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink>.
+ *
+ * Return value: a new #GDataMediaContent
+ **/
 GDataMediaContent *
 gdata_media_content_new (const gchar *uri, const gchar *type, gboolean is_default, GDataMediaExpression expression, gint duration, gint format)
 {
@@ -118,6 +198,12 @@ gdata_media_content_new (const gchar *uri, const gchar *type, gboolean is_defaul
 	return self;
 }
 
+/**
+ * gdata_media_content_free:
+ * @self: a #GDataMediaContent
+ *
+ * Frees a #GDataMediaContent.
+ **/
 void
 gdata_media_content_free (GDataMediaContent *self)
 {
@@ -129,6 +215,18 @@ gdata_media_content_free (GDataMediaContent *self)
 	g_slice_free (GDataMediaContent, self);
 }
 
+/**
+ * gdata_media_thumbnail_new:
+ * @uri: the thumbnail's URI
+ * @width: the thumbnail's width, in pixels, or %0
+ * @height: the thumbnail's height, in pixels, or %0
+ * @_time: the number of milliseconds into the media the thumbnail was taken, or %0
+ *
+ * Creates a new #GDataMediaThumbnail. More information is available in the <ulink type="http"
+ * url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink>.
+ *
+ * Return value: a new #GDataMediaThumbnail
+ **/
 GDataMediaThumbnail *
 gdata_media_thumbnail_new (const gchar *uri, guint width, guint height, gint64 _time)
 {
@@ -140,8 +238,19 @@ gdata_media_thumbnail_new (const gchar *uri, guint width, guint height, gint64 _
 	return self;
 }
 
-/* Parses a reduced version of NTP from http://www.ietf.org/rfc/rfc2326.txt.
- * See http://code.google.com/apis/youtube/2.0/reference.html#youtube_data_api_tag_media:thumbnail */
+/**
+ * gdata_media_thumbnail_parse_time:
+ * @time_string: a time string to parse
+ *
+ * Parses a time string in NTP format into a number of milliseconds since the
+ * start of a media stream.
+ *
+ * For more information about NTP format, see <ulink type="http" url="http://www.ietf.org/rfc/rfc2326.txt";>RFC 2326 3.6 Normal Play Time</ulink>.
+ *
+ * To build an NTP-format string, see gdata_media_thumbnail_build_time().
+ *
+ * Return value: number of milliseconds since the start of a media stream
+ **/
 gint64
 gdata_media_thumbnail_parse_time (const gchar *time_string)
 {
@@ -164,6 +273,15 @@ gdata_media_thumbnail_parse_time (const gchar *time_string)
 	return (gint64) ((seconds + minutes * 60 + hours * 3600) * 1000);
 }
 
+/**
+ * gdata_media_thumbnail_build_time:
+ * @_time: a number of milliseconds since the start of a media stream
+ *
+ * Builds an NTP-format time string describing @_time milliseconds since the start
+ * of a media stream.
+ *
+ * Return value: an NTP-format string describing @_time; free with g_free()
+ **/
 gchar *
 gdata_media_thumbnail_build_time (gint64 _time)
 {
@@ -181,6 +299,12 @@ gdata_media_thumbnail_build_time (gint64 _time)
 	return g_strdup_printf ("%02u:%02u:%02f", hours, minutes, seconds);
 }
 
+/**
+ * gdata_media_thumbnail_free:
+ * @self: a #GDataMediaThumbnail
+ *
+ * Frees a #GDataMediaThumbnail.
+ **/
 void
 gdata_media_thumbnail_free (GDataMediaThumbnail *self)
 {
diff --git a/gdata/gdata-media-rss.h b/gdata/gdata-media-rss.h
index 5eecee6..02eff23 100644
--- a/gdata/gdata-media-rss.h
+++ b/gdata/gdata-media-rss.h
@@ -24,45 +24,116 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GDataMediaRating:
+ * @country: a comma-delimited list of ISO 3166 country codes where the content is restricted
+ * @scheme: a URI identifying the rating scheme, or %NULL
+ *
+ * A structure fully representing a Media RSS "rating" element. The @country field is required,
+ * but the other is optional.
+ *
+ * See the <literal>media:rating</literal> element in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> for more information.
+ **/
 typedef struct {
-	gchar *scheme;
 	gchar *country;
+	gchar *scheme;
 } GDataMediaRating;
 
+/* TODO: Reverse the parameters */
 GDataMediaRating *gdata_media_rating_new (const gchar *scheme, const gchar *country) G_GNUC_WARN_UNUSED_RESULT;
 void gdata_media_rating_free (GDataMediaRating *self);
 
+/**
+ * GDataMediaRestriction:
+ * @countries: a space-delimited list of ISO 3166 country codes
+ * @relationship: %TRUE if the given @countries are not restricted regarding the content, %FALSE otherwise
+ *
+ * A structure fully representing a Media RSS "restriction" element. All fields are required.
+ *
+ * See the <literal>media:restriction</literal> element in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> for more information.
+ **/
 typedef struct {
-	gboolean relationship;
 	gchar *countries;
+	gboolean relationship;
+	/* TODO: Support uri and type */
 } GDataMediaRestriction;
 
 GDataMediaRestriction *gdata_media_restriction_new (const gchar *countries, gboolean relationship) G_GNUC_WARN_UNUSED_RESULT;
 void gdata_media_restriction_free (GDataMediaRestriction *self);
 
+/**
+ * GDataMediaCategory:
+ * @category: a category describing the content
+ * @label: a human-readable name for the category, or %NULL
+ * @scheme: a URI identifying the categorisation scheme, or %NULL
+ *
+ * A structure fully representing a Media RSS "category" element. The @category field is required,
+ * but the others are optional.
+ *
+ * See the <literal>media:category</literal> element in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> for more information.
+ **/
 typedef struct {
+	gchar *category;
 	gchar *label;
 	gchar *scheme;
-	gchar *category;
 } GDataMediaCategory;
 
 GDataMediaCategory *gdata_media_category_new (const gchar *category, const gchar *label, const gchar *scheme) G_GNUC_WARN_UNUSED_RESULT;
 void gdata_media_category_free (GDataMediaCategory *self);
 
+/**
+ * GDataMediaCredit:
+ * @credit: the username of someone who contributed towards the media
+ * @partner: %TRUE if the video was uploaded by a YouTube partner, %FALSE otherwise
+ *
+ * A structure fully representing a Media RSS "credit" element. All fields are required.
+ *
+ * See the <literal>media:credit</literal> element in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> for more information.
+ **/
 typedef struct {
 	gchar *credit;
 	gboolean partner;
+	/* TODO: add scheme and role */
+	/* TODO: partner is YouTube-specific */
 } GDataMediaCredit;
 
 GDataMediaCredit *gdata_media_credit_new (const gchar *credit, gboolean partner) G_GNUC_WARN_UNUSED_RESULT;
 void gdata_media_credit_free (GDataMediaCredit *self);
 
+/**
+ * GDataMediaExpression:
+ * @GDATA_MEDIA_EXPRESSION_SAMPLE: the media is a sample of a larger video
+ * @GDATA_MEDIA_EXPRESSION_FULL: the media is the full version
+ * @GDATA_MEDIA_EXPRESSION_NONSTOP: the media is a continuous stream
+ *
+ * An enum representing the possible values of #GDataMediaContent:expression.
+ **/
 typedef enum {
 	GDATA_MEDIA_EXPRESSION_SAMPLE,
 	GDATA_MEDIA_EXPRESSION_FULL,
 	GDATA_MEDIA_EXPRESSION_NONSTOP
 } GDataMediaExpression;
 
+/**
+ * GDataMediaContent:
+ * @uri: the media object's URI
+ * @type: the media object's MIME type, or %NULL
+ * @is_default: %TRUE if this is the default object for the media group, %FALSE otherwise
+ * @expression: whether this media is a full version or just a sample
+ * @duration: the length of the media, in seconds, or %-1
+ * @format: the video format of the media (see the <ulink type="http"
+ * url="http://code.google.com/apis/youtube/2.0/reference.html#youtube_data_api_tag_media:content";>YouTube specification</ulink>)
+ *
+ * A structure fully representing a Media RSS "content" element. The @uri field is required,
+ * but the others are optional.
+ *
+ * See the <literal>media:content</literal> element in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> for more information.
+ **/
 typedef struct {
 	gchar *uri;
 	gchar *type;
@@ -70,12 +141,26 @@ typedef struct {
 	GDataMediaExpression expression;
 	gint duration; /* TODO: Should be guint? */
 	gint format; /* TODO: YouTube-specific */
+	/* TODO: add support for other standard properties */
 } GDataMediaContent;
 
 GDataMediaContent *gdata_media_content_new (const gchar *uri, const gchar *type, gboolean is_default, GDataMediaExpression expression,
 					    gint duration, gint format) G_GNUC_WARN_UNUSED_RESULT;
 void gdata_media_content_free (GDataMediaContent *self);
 
+/**
+ * GDataMediaThumbnail:
+ * @uri: the thumbnail's URI
+ * @width: the thumbnail's width, in pixels, or %0
+ * @height: the thumbnail's height, in pixels, or %0
+ * @time: the number of milliseconds into the media the thumbnail was taken, or %0
+ *
+ * A structure fully representing a Media RSS "thumbnail" element. The @uri field is required,
+ * but the others are optional.
+ *
+ * See the <literal>media:thumbnail</literal> element in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> for more information.
+ **/
 typedef struct {
 	gchar *uri;
 	guint width;
diff --git a/gdata/services/youtube/gdata-youtube.c b/gdata/services/youtube/gdata-youtube.c
index e1313cc..343013c 100644
--- a/gdata/services/youtube/gdata-youtube.c
+++ b/gdata/services/youtube/gdata-youtube.c
@@ -19,10 +19,29 @@
 
 #include "gdata-youtube.h"
 
+/**
+ * gdata_youtube_state_new:
+ * @name: the publishing status of the video
+ * @reason_code: code providing information about why a video failed to upload or was rejected during processing
+ * @help_uri: a URI for a page explaining the problem
+ * @message: a human-readable message explaining the problem
+ *
+ * Creates a new #GDataYouTubeState. More information is available in the <ulink type="http"
+ * url="http://code.google.com/apis/youtube/2.0/reference.html#youtube_data_api_tag_yt:state";>YouTube specification</ulink>.
+ *
+ * Return value: a new #GDataYouTubeState
+ **/
 GDataYouTubeState *
 gdata_youtube_state_new (const gchar *name, const gchar *message, const gchar *reason_code, const gchar *help_uri)
 {
-	GDataYouTubeState *self = g_slice_new (GDataYouTubeState);
+	GDataYouTubeState *self;
+
+	g_return_val_if_fail (name != NULL, NULL);
+	g_return_val_if_fail (message != NULL, NULL);
+	g_return_val_if_fail (reason_code != NULL, NULL);
+	g_return_val_if_fail (help_uri != NULL, NULL);
+
+	self = g_slice_new (GDataYouTubeState);
 	self->name = g_strdup (name);
 	self->message = g_strdup (message);
 	self->reason_code = g_strdup (reason_code);
@@ -30,6 +49,12 @@ gdata_youtube_state_new (const gchar *name, const gchar *message, const gchar *r
 	return self;
 }
 
+/**
+ * gdata_youtube_state_free:
+ * @self: a #GDataYouTubeState
+ *
+ * Frees a #GDataYouTubeState.
+ **/
 void
 gdata_youtube_state_free (GDataYouTubeState *self)
 {
diff --git a/gdata/services/youtube/gdata-youtube.h b/gdata/services/youtube/gdata-youtube.h
index ecd74f2..d224736 100644
--- a/gdata/services/youtube/gdata-youtube.h
+++ b/gdata/services/youtube/gdata-youtube.h
@@ -24,6 +24,18 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GDataYouTubeState:
+ * @name: the publishing status of the video
+ * @reason_code: code providing information about why a video failed to upload or was rejected during processing
+ * @help_uri: a URI for a page explaining the problem
+ * @message: a human-readable message explaining the problem
+ *
+ * A structure fully representing a YouTube "state" element. All fields are required.
+ *
+ * See the <ulink type="http" url="http://code.google.com/apis/youtube/2.0/reference.html#youtube_data_api_tag_yt:state";>YouTube specification</ulink>
+ * for more information.
+ **/
 typedef struct {
 	gchar *name;
 	gchar *reason_code;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]