[libgdata] Added the last bits of API documentation

[Philip Withnall <pwithnall src gnome org>]

commit 5cbbe124c9b3659f30bd41ce7128e94639002669
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Apr 23 17:44:14 2009 +0100

    Added the last bits of API documentation
---
 docs/reference/gdata-docs.xml          |    1 +
 docs/reference/gdata-sections.txt      |   14 ++++++++++++
 gdata/gdata-media-rss.c                |   14 ++++++++++--
 gdata/gdata-types.c                    |   35 ++++++++++++++++++++++++++++++-
 gdata/gdata-types.h                    |    9 ++++++++
 gdata/services/youtube/Makefile.am     |    6 +++-
 gdata/services/youtube/gdata-youtube.c |   11 ++++++++++
 7 files changed, 83 insertions(+), 7 deletions(-)

diff --git a/docs/reference/gdata-docs.xml b/docs/reference/gdata-docs.xml
index 78856d7..1152c9b 100644
--- a/docs/reference/gdata-docs.xml
+++ b/docs/reference/gdata-docs.xml
@@ -17,6 +17,7 @@
 		<xi:include href="xml/gdata-query.xml"/>
 		<xi:include href="xml/gdata-feed.xml"/>
 		<xi:include href="xml/gdata-entry.xml"/>
+		<xi:include href="xml/gdata-types.xml"/>
 	</chapter>
 
 	<chapter>
diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index 80e1035..75fce40 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -253,6 +253,8 @@ gdata_youtube_service_upload_video
 gdata_youtube_service_get_developer_key
 gdata_youtube_service_get_youtube_user
 <SUBSECTION Standard>
+GDATA_TYPE_YOUTUBE_SERVICE_ERROR
+GDATA_TYPE_YOUTUBE_STANDARD_FEED_TYPE
 GDATA_YOUTUBE_SERVICE
 GDATA_YOUTUBE_SERVICE_CLASS
 GDATA_YOUTUBE_SERVICE_ERROR
@@ -548,3 +550,15 @@ GDATA_TYPE_CALENDAR_EVENT
 <SUBSECTION Private>
 GDataCalendarEventPrivate
 </SECTION>
+
+<SECTION>
+<FILE>gdata-types</FILE>
+<TITLE>GData Types</TITLE>
+GDataColor
+gdata_color_from_hexadecimal
+<SUBSECTION Standard>
+GDATA_TYPE_COLOR
+GDATA_TYPE_G_TIME_VAL
+gdata_color_get_type
+gdata_g_time_val_get_type
+</SECTION>
diff --git a/gdata/gdata-media-rss.c b/gdata/gdata-media-rss.c
index eebf8ad..f59dc69 100644
--- a/gdata/gdata-media-rss.c
+++ b/gdata/gdata-media-rss.c
@@ -17,14 +17,22 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-media
+ * @short_description: Media RSS namespace API
+ * @stability: Unstable
+ * @include: gdata/gdata-media-rss.h
+ *
+ * The structures here represent several core elements in the
+ * <ulink type="http" url="http://search.yahoo.com/mrss/";>Media RSS specification</ulink> which are used
+ * in some media-related GData APIs, in particular the YouTube API.
+ **/
+
 #include <stdlib.h>
 #include <string.h>
 
 #include "gdata-media-rss.h"
 
-/* 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
diff --git a/gdata/gdata-types.c b/gdata/gdata-types.c
index 2849603..6274834 100644
--- a/gdata/gdata-types.c
+++ b/gdata/gdata-types.c
@@ -17,6 +17,16 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-types
+ * @short_description: miscellaneous data types
+ * @stability: Unstable
+ * @include: gdata/gdata-types.h
+ *
+ * The structures here are used haphazardly across the library, describing
+ * various small data types.
+ **/
+
 #include <glib.h>
 #include <glib-object.h>
 #include <string.h>
@@ -65,15 +75,34 @@ gdata_color_get_type (void)
 	return type_id;
 }
 
+/**
+ * gdata_color_from_hexadecimal:
+ * @hexadecimal: a hexadecimal color string
+ * @color: a #GDataColor
+ *
+ * Parses @hexadecimal and returns a #GDataColor describing it in @color.
+ *
+ * @hexadecimal should be in the form <literal>#<replaceable>rr</replaceable><replaceable>gg</replaceable><replaceable>bb</replaceable></literal>,
+ * where <replaceable>rr</replaceable> is a two-digit hexadecimal red intensity value, <replaceable>gg</replaceable> is green
+ * and <replaceable>bb</replaceable> is blue. The hash is optional.
+ *
+ * Return value: %TRUE on success, %FALSE otherwise
+ **/
 gboolean
 gdata_color_from_hexadecimal (const gchar *hexadecimal, GDataColor *color)
 {
-	gchar *hex = (gchar*) hexadecimal;
+	gchar *hex;
+
+	g_return_val_if_fail (hexadecimal != NULL, FALSE);
+	g_return_val_if_fail (color != NULL, FALSE);
 
+	hex = g_strdup (hexadecimal);
 	if (*hex == '#')
 		hex++;
-	if (strlen (hex) != 6)
+	if (strlen (hex) != 6) {
+		g_free (hex);
 		return FALSE;
+	}
 
 	/* This is horrible and hacky, but should work */
 	color->blue = strtoul (hex + 4, NULL, 16);
@@ -82,5 +111,7 @@ gdata_color_from_hexadecimal (const gchar *hexadecimal, GDataColor *color)
 	*(hex + 2) = '\0';
 	color->red = strtoul (hex, NULL, 16);
 
+	g_free (hex);
+
 	return TRUE;
 }
diff --git a/gdata/gdata-types.h b/gdata/gdata-types.h
index f187e33..b899041 100644
--- a/gdata/gdata-types.h
+++ b/gdata/gdata-types.h
@@ -27,6 +27,15 @@ G_BEGIN_DECLS
 #define GDATA_TYPE_G_TIME_VAL (gdata_g_time_val_get_type ())
 GType gdata_g_time_val_get_type (void) G_GNUC_CONST;
 
+/**
+ * GDataColor:
+ * @red: red color intensity, from 0â??255
+ * @green: green color intensity, from 0â??255
+ * @blue: blue color intensity, from 0â??255
+ *
+ * Describes a color, such as used in the Google Calendar interface to
+ * differentiate calendars.
+ **/
 typedef struct {
 	guint16 red;
 	guint16 green;
diff --git a/gdata/services/youtube/Makefile.am b/gdata/services/youtube/Makefile.am
index c1540d9..b933df7 100644
--- a/gdata/services/youtube/Makefile.am
+++ b/gdata/services/youtube/Makefile.am
@@ -9,8 +9,10 @@ gdata-youtube-enums.h: $(gdatayoutubeinclude_HEADERS) Makefile
 			--fprod "/* enumerations from \"@filename \" */\n" \
 			--vhead "GType @enum_name _get_type (void) G_GNUC_CONST;\n#define GDATA_TYPE_ ENUMSHORT@ (@enum_name _get_type())\n" \
 			--ftail "G_END_DECLS\n\n#endif /* !GDATA_YOUTUBE_ENUMS_H */" $(gdatayoutubeinclude_HEADERS)) > gdata-youtube-enums.h.tmp \
-	&& sed "s/g_data_you_tube/gdata_youtube/" gdata-youtube-enums.h.tmp > gdata-youtube-enums.h \
-	&& rm -f gdata-youtube-enums.h.tmp
+	&& sed "s/g_data_you_tube/gdata_youtube/" gdata-youtube-enums.h.tmp > gdata-youtube-enums.h.tmp2 \
+	&& sed "s/GDATA_TYPE_DATA_YOU_TUBE/GDATA_TYPE_YOUTUBE/" gdata-youtube-enums.h.tmp2 > gdata-youtube-enums.h \
+	&& rm -f gdata-youtube-enums.h.tmp \
+	&& rm -f gdata-youtube-enums.h.tmp2
 
 gdata-youtube-enums.c: $(gdatayoutubeinclude_HEADERS) Makefile gdata-youtube-enums.h
 	(cd $(srcdir) && $(GLIB_MKENUMS) \
diff --git a/gdata/services/youtube/gdata-youtube.c b/gdata/services/youtube/gdata-youtube.c
index 343013c..b7cd49f 100644
--- a/gdata/services/youtube/gdata-youtube.c
+++ b/gdata/services/youtube/gdata-youtube.c
@@ -17,6 +17,17 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-youtube
+ * @short_description: YouTube namespace API
+ * @stability: Unstable
+ * @include: gdata/services/youtube/gdata-youtube.h
+ *
+ * The structures here represent several core elements in the
+ * <ulink type="http" url="http://code.google.com/apis/youtube/2.0/reference.html#YouTube_elements_reference";>YouTube specification</ulink>
+ * which are used exclusively in the YouTube API.
+ **/
+
 #include "gdata-youtube.h"
 
 /**