[libgdata] [docs] Standardised documentation a little better
- From: Philip Withnall <pwithnall src gnome org>
- To: svn-commits-list gnome org
- Subject: [libgdata] [docs] Standardised documentation a little better
- Date: Fri, 24 Apr 2009 14:16:06 -0400 (EDT)
commit fe0d4b5ec37fe451e3f76b0952f8eb6afae6622e
Author: Philip Withnall <philip tecnocode co uk>
Date: Fri Apr 24 18:40:48 2009 +0100
[docs] Standardised documentation a little better
---
gdata/gdata-atom.c | 8 ++--
gdata/gdata-feed.c | 6 +-
gdata/gdata-gdata.c | 22 +++++-----
gdata/gdata-media-rss.c | 50 ++++++++++++++++-----
gdata/gdata-query.c | 8 ++--
gdata/services/calendar/gdata-calendar-calendar.c | 2 +-
gdata/services/calendar/gdata-calendar-event.c | 2 +-
gdata/services/calendar/gdata-calendar-query.c | 8 ++--
gdata/services/contacts/gdata-contacts-contact.c | 2 +-
gdata/services/youtube/gdata-youtube-video.c | 2 +-
gdata/services/youtube/gdata-youtube.c | 2 +-
11 files changed, 69 insertions(+), 43 deletions(-)
diff --git a/gdata/gdata-atom.c b/gdata/gdata-atom.c
index 7d7db0b..8d4d622 100644
--- a/gdata/gdata-atom.c
+++ b/gdata/gdata-atom.c
@@ -41,7 +41,7 @@
*
* All the parameters are copied, so can be freed after calling this function.
*
- * Return value: a new #GDataCategory, or %NULL on error
+ * Return value: a new #GDataCategory, or %NULL; free with gdata_category_free()
**/
GDataCategory *
gdata_category_new (const gchar *term, const gchar *scheme, const gchar *label)
@@ -89,7 +89,7 @@ gdata_category_free (GDataCategory *self)
*
* All the parameters are copied, so can be freed after calling this function.
*
- * Return value: a new #GDataLink, or %NULL on error
+ * Return value: a new #GDataLink, or %NULL; free with gdata_link_free()
**/
GDataLink *
gdata_link_new (const gchar *href, const gchar *rel, const gchar *type, const gchar *hreflang, const gchar *title, gint length)
@@ -141,7 +141,7 @@ gdata_link_free (GDataLink *self)
*
* All the parameters are copied, so can be freed after calling this function.
*
- * Return value: a new #GDataAuthor, or %NULL on error
+ * Return value: a new #GDataAuthor, or %NULL; free with gdata_author_free()
**/
GDataAuthor *
gdata_author_new (const gchar *name, const gchar *uri, const gchar *email)
@@ -186,7 +186,7 @@ gdata_author_free (GDataAuthor *self)
*
* All the parameters are copied, so can be freed after calling this function.
*
- * Return value: a new #GDataGenerator, or %NULL on error
+ * Return value: a new #GDataGenerator, or %NULL; free with gdata_generator_free()
**/
GDataGenerator *
gdata_generator_new (const gchar *name, const gchar *uri, const gchar *version)
diff --git a/gdata/gdata-feed.c b/gdata/gdata-feed.c
index 5fd9b90..e990018 100644
--- a/gdata/gdata-feed.c
+++ b/gdata/gdata-feed.c
@@ -963,7 +963,7 @@ gdata_feed_get_generator (GDataFeed *self)
*
* Returns the number of items per results page feed.
*
- * Return value: the number of items per results page feed, or 0 on error
+ * Return value: the number of items per results page feed, or %0
**/
guint
gdata_feed_get_items_per_page (GDataFeed *self)
@@ -978,7 +978,7 @@ gdata_feed_get_items_per_page (GDataFeed *self)
*
* Returns the one-based start index of the results feed in the result set.
*
- * Return value: the one-based start index, or 0 on error
+ * Return value: the one-based start index, or %0
**/
guint
gdata_feed_get_start_index (GDataFeed *self)
@@ -994,7 +994,7 @@ gdata_feed_get_start_index (GDataFeed *self)
* Returns the total number of results in the result set, including results on other
* pages.
*
- * Return value: the total number of results, or 0 on error
+ * Return value: the total number of results, or %0
**/
guint
gdata_feed_get_total_results (GDataFeed *self)
diff --git a/gdata/gdata-gdata.c b/gdata/gdata-gdata.c
index e85fdac..8b1b576 100644
--- a/gdata/gdata-gdata.c
+++ b/gdata/gdata-gdata.c
@@ -43,7 +43,7 @@
*
* Currently, rel and value functionality is not implemented in #GDataGDRating.
*
- * Return value: a new #GDataGDRating
+ * Return value: a new #GDataGDRating; free with gdata_gd_rating_free()
**/
GDataGDRating *
gdata_gd_rating_new (guint min, guint max, guint num_raters, gdouble average)
@@ -82,7 +82,7 @@ gdata_gd_rating_free (GDataGDRating *self)
*
* Currently, readOnly and feed functionality is not implemented in #GDataGDFeedLink.
*
- * Return value: a new #GDataGDFeedLink, or %NULL on error
+ * Return value: a new #GDataGDFeedLink, or %NULL; free with gdata_gd_feed_link_free()
**/
GDataGDFeedLink *
gdata_gd_feed_link_new (const gchar *href, const gchar *rel, guint count_hint)
@@ -129,7 +129,7 @@ gdata_gd_feed_link_free (GDataGDFeedLink *self)
* This function takes ownership of @reminders, so the list (or its entries) must not be freed
* by the caller after a call to gdata_gd_when_new has finished.
*
- * Return value: a new #GDataGDWhen, or %NULL on error
+ * Return value: a new #GDataGDWhen, or %NULL; free with gdata_gd_when_free()
**/
GDataGDWhen *
gdata_gd_when_new (GTimeVal *start_time, GTimeVal *end_time, gboolean is_date, const gchar *value_string, GList *reminders)
@@ -184,7 +184,7 @@ gdata_gd_when_free (GDataGDWhen *self)
*
* Currently, entryLink functionality is not implemented in #GDataGDWho.
*
- * Return value: a new #GDataGDWho
+ * Return value: a new #GDataGDWho; free with gdata_gd_who_free()
**/
GDataGDWho *
gdata_gd_who_new (const gchar *rel, const gchar *value_string, const gchar *email)
@@ -225,7 +225,7 @@ gdata_gd_who_free (GDataGDWho *self)
*
* Currently, entryLink functionality is not implemented in #GDataGDWhere.
*
- * Return value: a new #GDataGDWhere
+ * Return value: a new #GDataGDWhere; free with gdata_gd_where_free()
**/
GDataGDWhere *
gdata_gd_where_new (const gchar *rel, const gchar *value_string, const gchar *label)
@@ -265,7 +265,7 @@ gdata_gd_where_free (GDataGDWhere *self)
* Creates a new #GDataGDEmailAddress. More information is available in the <ulink type="http"
* url="http://code.google.com/apis/gdata/elements.html#gdEmail">GData specification</ulink>.
*
- * Return value: a new #GDataGDEmailAddress, or %NULL on error
+ * Return value: a new #GDataGDEmailAddress, or %NULL; free with gdata_gd_email_address_free()
**/
GDataGDEmailAddress *
gdata_gd_email_address_new (const gchar *address, const gchar *rel, const gchar *label, gboolean primary)
@@ -311,7 +311,7 @@ gdata_gd_email_address_free (GDataGDEmailAddress *self)
* Creates a new #GDataGDIMAddress. More information is available in the <ulink type="http"
* url="http://code.google.com/apis/gdata/elements.html#gdIm">GData specification</ulink>.
*
- * Return value: a new #GDataGDIMAddress, or %NULL on error
+ * Return value: a new #GDataGDIMAddress, or %NULL; free with gdata_gd_im_address_free()
**/
GDataGDIMAddress *
gdata_gd_im_address_new (const gchar *address, const gchar *protocol, const gchar *rel, const gchar *label, gboolean primary)
@@ -360,7 +360,7 @@ gdata_gd_im_address_free (GDataGDIMAddress *self)
* Creates a new #GDataGDPhoneNumber. More information is available in the <ulink type="http"
* url="http://code.google.com/apis/gdata/elements.html#gdPhoneNumber">GData specification</ulink>.
*
- * Return value: a new #GDataGDPhoneNumber, or %NULL on error
+ * Return value: a new #GDataGDPhoneNumber, or %NULL; free with gdata_gd_phone_number_free()
**/
GDataGDPhoneNumber *
gdata_gd_phone_number_new (const gchar *number, const gchar *rel, const gchar *label, const gchar *uri, gboolean primary)
@@ -407,7 +407,7 @@ gdata_gd_phone_number_free (GDataGDPhoneNumber *self)
* Creates a new #GDataGDPostalAddress. More information is available in the <ulink type="http"
* url="http://code.google.com/apis/gdata/elements.html#gdPostalAddress">GData specification</ulink>.
*
- * Return value: a new #GDataGDPostalAddress, or %NULL on error
+ * Return value: a new #GDataGDPostalAddress, or %NULL; free with gdata_gd_postal_address_free()
**/
GDataGDPostalAddress *
gdata_gd_postal_address_new (const gchar *address, const gchar *rel, const gchar *label, gboolean primary)
@@ -453,7 +453,7 @@ gdata_gd_postal_address_free (GDataGDPostalAddress *self)
* Creates a new #GDataGDOrganization. More information is available in the <ulink type="http"
* url="http://code.google.com/apis/gdata/elements.html#gdOrganization">GData specification</ulink>.
*
- * Return value: a new #GDataGDOrganization, or %NULL on error
+ * Return value: a new #GDataGDOrganization, or %NULL; free with gdata_gd_organization_free()
**/
GDataGDOrganization *
gdata_gd_organization_new (const gchar *name, const gchar *title, const gchar *rel, const gchar *label, gboolean primary)
@@ -497,7 +497,7 @@ gdata_gd_organization_free (GDataGDOrganization *self)
* Creates a new #GDataGDReminder. More information is available in the <ulink type="http"
* url="http://code.google.com/apis/gdata/elements.html#gdReminder">GData specification</ulink>.
*
- * Return value: a new #GDataGDReminder, or %NULL on error
+ * Return value: a new #GDataGDReminder, or %NULL; free with gdata_gd_reminder_free()
**/
GDataGDReminder *
gdata_gd_reminder_new (const gchar *method, GTimeVal *absolute_time, gint days, gint hours, gint minutes)
diff --git a/gdata/gdata-media-rss.c b/gdata/gdata-media-rss.c
index f59dc69..6615f7b 100644
--- a/gdata/gdata-media-rss.c
+++ b/gdata/gdata-media-rss.c
@@ -41,12 +41,16 @@
* 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
+ * Return value: a new #GDataMediaRating, or %NULL; free with gdata_media_rating_free()
**/
GDataMediaRating *
gdata_media_rating_new (const gchar *scheme, const gchar *country)
{
- GDataMediaRating *self = g_slice_new (GDataMediaRating);
+ GDataMediaRating *self;
+
+ g_return_val_if_fail (country != NULL, NULL);
+
+ self = g_slice_new (GDataMediaRating);
self->scheme = g_strdup (scheme);
self->country = g_strdup (country);
return self;
@@ -77,12 +81,16 @@ gdata_media_rating_free (GDataMediaRating *self)
* 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
+ * Return value: a new #GDataMediaRestriction, or %NULL; free with gdata_media_restriction_free()
**/
GDataMediaRestriction *
gdata_media_restriction_new (const gchar *countries, gboolean relationship)
{
- GDataMediaRestriction *self = g_slice_new (GDataMediaRestriction);
+ GDataMediaRestriction *self;
+
+ g_return_val_if_fail (countries != NULL, NULL);
+
+ self = g_slice_new (GDataMediaRestriction);
self->countries = g_strdup (countries);
self->relationship = relationship;
return self;
@@ -113,12 +121,16 @@ gdata_media_restriction_free (GDataMediaRestriction *self)
* 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
+ * Return value: a new #GDataMediaCategory, or %NULL; free with gdata_media_category_free()
**/
GDataMediaCategory *
gdata_media_category_new (const gchar *category, const gchar *label, const gchar *scheme)
{
- GDataMediaCategory *self = g_slice_new (GDataMediaCategory);
+ GDataMediaCategory *self;
+
+ g_return_val_if_fail (category != NULL, NULL);
+
+ self = g_slice_new (GDataMediaCategory);
self->category = g_strdup (category);
self->label = g_strdup (label);
self->scheme = g_strdup (scheme);
@@ -151,12 +163,16 @@ gdata_media_category_free (GDataMediaCategory *self)
* 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
+ * Return value: a new #GDataMediaCredit, or %NULL; free with gdata_media_credit_free()
**/
GDataMediaCredit *
gdata_media_credit_new (const gchar *credit, gboolean partner)
{
- GDataMediaCredit *self = g_slice_new (GDataMediaCredit);
+ GDataMediaCredit *self;
+
+ g_return_val_if_fail (credit != NULL, NULL);
+
+ self = g_slice_new (GDataMediaCredit);
self->credit = g_strdup (credit);
self->partner = partner;
return self;
@@ -191,12 +207,16 @@ gdata_media_credit_free (GDataMediaCredit *self)
* 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
+ * Return value: a new #GDataMediaContent, or %NULL; free with gdata_media_content_free()
**/
GDataMediaContent *
gdata_media_content_new (const gchar *uri, const gchar *type, gboolean is_default, GDataMediaExpression expression, gint duration, gint format)
{
- GDataMediaContent *self = g_slice_new (GDataMediaContent);
+ GDataMediaContent *self;
+
+ g_return_val_if_fail (uri != NULL, NULL);
+
+ self = g_slice_new (GDataMediaContent);
self->uri = g_strdup (uri);
self->type = g_strdup (type);
self->is_default = is_default;
@@ -233,12 +253,16 @@ gdata_media_content_free (GDataMediaContent *self)
* 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
+ * Return value: a new #GDataMediaThumbnail, or %NULL; free with gdata_media_thumbnail_free()
**/
GDataMediaThumbnail *
gdata_media_thumbnail_new (const gchar *uri, guint width, guint height, gint64 _time)
{
- GDataMediaThumbnail *self = g_slice_new (GDataMediaThumbnail);
+ GDataMediaThumbnail *self;
+
+ g_return_val_if_fail (uri != NULL, NULL);
+
+ self = g_slice_new (GDataMediaThumbnail);
self->uri = g_strdup (uri);
self->width = width;
self->height = height;
@@ -266,6 +290,8 @@ gdata_media_thumbnail_parse_time (const gchar *time_string)
gfloat seconds;
gchar *end_pointer;
+ g_return_val_if_fail (time_string != NULL, 0);
+
hours = strtoul (time_string, &end_pointer, 10);
if (end_pointer != time_string + 2)
return -1;
diff --git a/gdata/gdata-query.c b/gdata/gdata-query.c
index 8e3535e..f8b6169 100644
--- a/gdata/gdata-query.c
+++ b/gdata/gdata-query.c
@@ -717,7 +717,7 @@ gdata_query_set_author (GDataQuery *self, const gchar *author)
* @updated_min: a #GTimeVal
*
* Gets the #GDataQuery:updated-min property and puts it in @updated_min. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_query_get_updated_min (GDataQuery *self, GTimeVal *updated_min)
@@ -759,7 +759,7 @@ gdata_query_set_updated_min (GDataQuery *self, GTimeVal *updated_min)
* @updated_max: a #GTimeVal
*
* Gets the #GDataQuery:updated-max property and puts it in @updated_max. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_query_get_updated_max (GDataQuery *self, GTimeVal *updated_max)
@@ -801,7 +801,7 @@ gdata_query_set_updated_max (GDataQuery *self, GTimeVal *updated_max)
* @published_min: a #GTimeVal
*
* Gets the #GDataQuery:published-min property and puts it in @published_min. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_query_get_published_min (GDataQuery *self, GTimeVal *published_min)
@@ -843,7 +843,7 @@ gdata_query_set_published_min (GDataQuery *self, GTimeVal *published_min)
* @published_max: a #GTimeVal
*
* Gets the #GDataQuery:published-max property and puts it in @published_max. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_query_get_published_max (GDataQuery *self, GTimeVal *published_max)
diff --git a/gdata/services/calendar/gdata-calendar-calendar.c b/gdata/services/calendar/gdata-calendar-calendar.c
index 77fccd0..d8b7ee3 100644
--- a/gdata/services/calendar/gdata-calendar-calendar.c
+++ b/gdata/services/calendar/gdata-calendar-calendar.c
@@ -552,7 +552,7 @@ gdata_calendar_calendar_get_access_level (GDataCalendarCalendar *self)
* @edited: a #GTimeVal
*
* Gets the #GDataCalendarCalendar:edited property and puts it in @edited. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_calendar_calendar_get_edited (GDataCalendarCalendar *self, GTimeVal *edited)
diff --git a/gdata/services/calendar/gdata-calendar-event.c b/gdata/services/calendar/gdata-calendar-event.c
index 63548f6..72c9596 100644
--- a/gdata/services/calendar/gdata-calendar-event.c
+++ b/gdata/services/calendar/gdata-calendar-event.c
@@ -710,7 +710,7 @@ get_namespaces (GDataEntry *entry, GHashTable *namespaces)
* @edited: a #GTimeVal
*
* Gets the #GDataCalendarEvent:edited property and puts it in @edited. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_calendar_event_get_edited (GDataCalendarEvent *self, GTimeVal *edited)
diff --git a/gdata/services/calendar/gdata-calendar-query.c b/gdata/services/calendar/gdata-calendar-query.c
index e3ab2a1..7a5a29f 100644
--- a/gdata/services/calendar/gdata-calendar-query.c
+++ b/gdata/services/calendar/gdata-calendar-query.c
@@ -483,7 +483,7 @@ gdata_calendar_query_set_order_by (GDataCalendarQuery *self, const gchar *order_
* @start: a #GTimeVal
*
* Gets the #GDataCalendarQuery:recurrence-expansion-start property and puts it
- * in @start. If the property is unset, both fields in the #GTimeVal will be set to 0.
+ * in @start. If the property is unset, both fields in the #GTimeVal will be set to %0.
**/
void
gdata_calendar_query_get_recurrence_expansion_start (GDataCalendarQuery *self, GTimeVal *start)
@@ -524,7 +524,7 @@ gdata_calendar_query_set_recurrence_expansion_start (GDataCalendarQuery *self, G
* @end: a #GTimeVal
*
* Gets the #GDataCalendarQuery:recurrence-expansion-end property and puts it
- * in @end. If the property is unset, both fields in the #GTimeVal will be set to 0.
+ * in @end. If the property is unset, both fields in the #GTimeVal will be set to %0.
**/
void
gdata_calendar_query_get_recurrence_expansion_end (GDataCalendarQuery *self, GTimeVal *end)
@@ -629,7 +629,7 @@ gdata_calendar_query_set_sort_order (GDataCalendarQuery *self, const gchar *sort
* @start_min: a #GTimeVal
*
* Gets the #GDataCalendarQuery:start-min property and puts it
- * in @start_min. If the property is unset, both fields in the #GTimeVal will be set to 0.
+ * in @start_min. If the property is unset, both fields in the #GTimeVal will be set to %0.
**/
void
gdata_calendar_query_get_start_min (GDataCalendarQuery *self, GTimeVal *start_min)
@@ -670,7 +670,7 @@ gdata_calendar_query_set_start_min (GDataCalendarQuery *self, GTimeVal *start_mi
* @start_max: a #GTimeVal
*
* Gets the #GDataCalendarQuery:start-max property and puts it
- * in @start_max. If the property is unset, both fields in the #GTimeVal will be set to 0.
+ * in @start_max. If the property is unset, both fields in the #GTimeVal will be set to %0.
**/
void
gdata_calendar_query_get_start_max (GDataCalendarQuery *self, GTimeVal *start_max)
diff --git a/gdata/services/contacts/gdata-contacts-contact.c b/gdata/services/contacts/gdata-contacts-contact.c
index d57fdd8..f4ea09f 100644
--- a/gdata/services/contacts/gdata-contacts-contact.c
+++ b/gdata/services/contacts/gdata-contacts-contact.c
@@ -647,7 +647,7 @@ get_namespaces (GDataEntry *entry, GHashTable *namespaces)
* @edited: a #GTimeVal
*
* Gets the #GDataContactsContact:edited property and puts it in @edited. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_contacts_contact_get_edited (GDataContactsContact *self, GTimeVal *edited)
diff --git a/gdata/services/youtube/gdata-youtube-video.c b/gdata/services/youtube/gdata-youtube-video.c
index 01970ff..9c07f54 100644
--- a/gdata/services/youtube/gdata-youtube-video.c
+++ b/gdata/services/youtube/gdata-youtube-video.c
@@ -1526,7 +1526,7 @@ gdata_youtube_video_set_is_private (GDataYouTubeVideo *self, gboolean is_private
* @uploaded: a #GTimeVal
*
* Gets the #GDataYouTubeVideo:uploaded property and puts it in @uploaded. If the property is unset,
- * both fields in the #GTimeVal will be set to 0.
+ * both fields in the #GTimeVal will be set to %0.
**/
void
gdata_youtube_video_get_uploaded (GDataYouTubeVideo *self, GTimeVal *uploaded)
diff --git a/gdata/services/youtube/gdata-youtube.c b/gdata/services/youtube/gdata-youtube.c
index b7cd49f..cfef839 100644
--- a/gdata/services/youtube/gdata-youtube.c
+++ b/gdata/services/youtube/gdata-youtube.c
@@ -40,7 +40,7 @@
* 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
+ * Return value: a new #GDataYouTubeState, or %NULL; free with gdata_youtube_state_free()
**/
GDataYouTubeState *
gdata_youtube_state_new (const gchar *name, const gchar *message, const gchar *reason_code, const gchar *help_uri)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]