GNOME.org
 

[libgdata] Added API documentation for GDataCalendarService and GDataCalendarQuery

commit c41114dd844d9f30ad0e8053085fe4eec3097993
Author: Philip Withnall <philip tecnocode co uk>
Date:   Wed Apr 22 16:25:54 2009 +0100

    Added API documentation for GDataCalendarService and GDataCalendarQuery
---
 docs/reference/gdata-docs.xml                    |    6 +
 docs/reference/gdata-sections.txt                |   65 ++++-
 gdata/services/calendar/gdata-calendar-query.c   |  342 +++++++++++++++++++---
 gdata/services/calendar/gdata-calendar-query.h   |   15 +-
 gdata/services/calendar/gdata-calendar-service.c |  123 ++++++++-
 gdata/services/calendar/gdata-calendar-service.h |   11 +
 6 files changed, 516 insertions(+), 46 deletions(-)

diff --git a/docs/reference/gdata-docs.xml b/docs/reference/gdata-docs.xml
index a5c9e8d..6ce41e1 100644
--- a/docs/reference/gdata-docs.xml
+++ b/docs/reference/gdata-docs.xml
@@ -32,6 +32,12 @@
 	</chapter>
 
 	<chapter>
+		<title>Google Calendar API</title>
+		<xi:include href="xml/gdata-calendar-service.xml"/>
+		<xi:include href="xml/gdata-calendar-query.xml"/>
+	</chapter>
+
+	<chapter>
 		<title>Google Contacts API</title>
 		<xi:include href="xml/gdata-contacts-service.xml"/>
 		<xi:include href="xml/gdata-contacts-query.xml"/>
diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index 7191b28..a938a73 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -313,10 +313,10 @@ gdata_contacts_query_new
 gdata_contacts_query_new_with_limits
 gdata_contacts_query_get_order_by
 gdata_contacts_query_set_order_by
-gdata_contacts_query_show_deleted
-gdata_contacts_query_set_show_deleted
 gdata_contacts_query_get_sort_order
 gdata_contacts_query_set_sort_order
+gdata_contacts_query_show_deleted
+gdata_contacts_query_set_show_deleted
 gdata_contacts_query_get_group
 gdata_contacts_query_set_group
 <SUBSECTION Standard>
@@ -372,3 +372,64 @@ GDATA_TYPE_CONTACTS_CONTACT
 <SUBSECTION Private>
 GDataContactsContactPrivate
 </SECTION>
+
+<SECTION>
+<FILE>gdata-calendar-service</FILE>
+<TITLE>GDataCalendarService</TITLE>
+GDataCalendarService
+GDataCalendarServiceClass
+gdata_calendar_service_new
+gdata_calendar_service_query_all_calendars
+gdata_calendar_service_query_all_calendars_async
+gdata_calendar_service_query_own_calendars
+gdata_calendar_service_query_own_calendars_async
+gdata_calendar_service_query_events
+gdata_calendar_service_insert_event
+<SUBSECTION Standard>
+gdata_calendar_service_get_type
+GDATA_CALENDAR_SERVICE
+GDATA_CALENDAR_SERVICE_CLASS
+GDATA_CALENDAR_SERVICE_GET_CLASS
+GDATA_IS_CALENDAR_SERVICE
+GDATA_IS_CALENDAR_SERVICE_CLASS
+GDATA_TYPE_CALENDAR_SERVICE
+<SUBSECTION Private>
+GDataCalendarServicePrivate
+</SECTION>
+
+<SECTION>
+<FILE>gdata-calendar-query</FILE>
+<TITLE>GDataCalendarQuery</TITLE>
+GDataCalendarQuery
+GDataCalendarQueryClass
+gdata_calendar_query_new
+gdata_calendar_query_new_with_limits
+gdata_calendar_query_get_future_events
+gdata_calendar_query_set_future_events
+gdata_calendar_query_get_single_events
+gdata_calendar_query_set_single_events
+gdata_calendar_query_get_order_by
+gdata_calendar_query_set_order_by
+gdata_calendar_query_get_sort_order
+gdata_calendar_query_set_sort_order
+gdata_calendar_query_get_start_min
+gdata_calendar_query_set_start_min
+gdata_calendar_query_get_start_max
+gdata_calendar_query_set_start_max
+gdata_calendar_query_get_recurrence_expansion_start
+gdata_calendar_query_set_recurrence_expansion_start
+gdata_calendar_query_get_recurrence_expansion_end
+gdata_calendar_query_set_recurrence_expansion_end
+gdata_calendar_query_get_timezone
+gdata_calendar_query_set_timezone
+<SUBSECTION Standard>
+gdata_calendar_query_get_type
+GDATA_CALENDAR_QUERY
+GDATA_CALENDAR_QUERY_CLASS
+GDATA_CALENDAR_QUERY_GET_CLASS
+GDATA_IS_CALENDAR_QUERY
+GDATA_IS_CALENDAR_QUERY_CLASS
+GDATA_TYPE_CALENDAR_QUERY
+<SUBSECTION Private>
+GDataCalendarQueryPrivate
+</SECTION>
diff --git a/gdata/services/calendar/gdata-calendar-query.c b/gdata/services/calendar/gdata-calendar-query.c
index e58f78b..7cb96cc 100644
--- a/gdata/services/calendar/gdata-calendar-query.c
+++ b/gdata/services/calendar/gdata-calendar-query.c
@@ -17,6 +17,19 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-calendar-query
+ * @short_description: GData Calendar query object
+ * @stability: Unstable
+ * @include: gdata/services/calendar/gdata-calendar-query.h
+ *
+ * #GDataCalendarQuery represents a collection of query parameters specific to the Google Calendar service, which go above and beyond
+ * those catered for by #GDataQuery.
+ *
+ * For more information on the custom GData query parameters supported by #GDataCalendarQuery, see the <ulink type="http"
+ * url="http://code.google.com/apis/calendar/docs/2.0/reference.html#Parameters";>online documentation</ulink>.
+ **/
+
 #include <config.h>
 #include <glib.h>
 #include <glib/gi18n-lib.h>
@@ -35,17 +48,13 @@ static void gdata_calendar_query_set_property (GObject *object, guint property_i
 struct _GDataCalendarQueryPrivate {
 	gboolean future_events;
 	gchar *order_by; /* TODO: enum? #defined values? */
-	gboolean recurrence_expansion_start_set;
 	GTimeVal recurrence_expansion_start;
-	gboolean recurrence_expansion_end_set;
 	GTimeVal recurrence_expansion_end;
 	gboolean single_events;
 	gchar *sort_order; /* TODO: enum? */
-	gboolean start_min_set;
 	GTimeVal start_min;
-	gboolean start_max_set;
 	GTimeVal start_max;
-	gchar *ctz;
+	gchar *timezone;
 };
 
 enum {
@@ -57,7 +66,7 @@ enum {
 	PROP_SORT_ORDER,
 	PROP_START_MIN,
 	PROP_START_MAX,
-	PROP_CTZ
+	PROP_TIMEZONE
 };
 
 G_DEFINE_TYPE (GDataCalendarQuery, gdata_calendar_query, GDATA_TYPE_QUERY)
@@ -74,49 +83,116 @@ gdata_calendar_query_class_init (GDataCalendarQueryClass *klass)
 	gobject_class->get_property = gdata_calendar_query_get_property;
 	gobject_class->finalize = gdata_calendar_query_finalize;
 
+	/**
+	 * GDataCalendarQuery:future-events:
+	 *
+	 * A shortcut to request all events that are scheduled for future times. Overrides the
+	 * #GDataCalendarQuery:recurrence-expansion-start, #GDataCalendarQuery:recurrence-expansion-end,
+	 * #GDataCalendarQuery:start-min and #GDataCalendarQuery:start-max properties.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_FUTURE_EVENTS,
 				g_param_spec_boolean ("future-events",
-					"Future events", "TODO",
+					"Future events?", "A shortcut to request all events that are scheduled for future times.",
 					FALSE,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:order-by:
+	 *
+	 * Specifies order of entries in a feed. Supported values are <literal>lastmodified</literal> and
+	 * <literal>starttime</literal>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_ORDER_BY,
 				g_param_spec_string ("order-by",
-					"Order by", "TODO",
+					"Order by", "Specifies order of entries in a feed.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:recurrence-expansion-start:
+	 *
+	 * Specifies beginning of time period for which to expand recurring events, inclusive.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_RECURRENCE_EXPANSION_START,
 				g_param_spec_boxed ("recurrence-expansion-start",
-					"Recurrence expansion start", "TODO",
+					"Recurrence expansion start", "Specifies beginning of time period for which to expand recurring events.",
 					G_TYPE_TIME_VAL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:recurrence-expansion-end:
+	 *
+	 * Specifies end of time period for which to expand recurring events, exclusive.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_RECURRENCE_EXPANSION_END,
 				g_param_spec_boxed ("recurrence-expansion-end",
-					"Recurrence expansion end", "TODO",
+					"Recurrence expansion end", "Specifies end of time period for which to expand recurring events.",
 					G_TYPE_TIME_VAL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:single-events:
+	 *
+	 * Indicates whether recurring events should be expanded or represented as a single event.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_SINGLE_EVENTS,
 				g_param_spec_boolean ("single-events",
-					"Single events", "TODO",
+					"Single events?", "Indicates whether recurring events should be expanded or represented as a single event.",
 					FALSE,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:sort-order:
+	 *
+	 * Specifies direction of sorting. Supported values are <literal>ascending</literal> and
+	 * <literal>descending</literal>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_SORT_ORDER,
 				g_param_spec_string ("sort-order",
-					"Sort order", "TODO",
+					"Sort order", "Specifies direction of sorting.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:start-min:
+	 *
+	 * Together with #GDataCalendarQuery:start-max creates a timespan such that only events that are within the timespan are returned.
+	 *
+	 * #GDataCalendarQuery:start-min is inclusive, while #GDataCalendarQuery:start-max is exclusive. Events that overlap the range are
+	 * included.
+	 *
+	 * If not specified, the default #GDataCalendarQuery:start-min is <literal>1970-01-01</literal>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_START_MIN,
 				g_param_spec_boxed ("start-min",
-					"Start min", "TODO",
+					"Start min", "A timespan such that only events that are within the timespan are returned.",
 					G_TYPE_TIME_VAL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataCalendarQuery:start-max:
+	 *
+	 * Together with #GDataCalendarQuery:start-min creates a timespan such that only events that are within the timespan are returned
+	 *
+	 * #GDataCalendarQuery:start-min is inclusive, while #GDataCalendarQuery:start-max is exclusive. Events that overlap the range are
+	 * included.
+	 *
+	 * If not specified, the default #GDataCalendarQuery:start-max is <literal>2031-01-01</literal>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_START_MAX,
 				g_param_spec_boxed ("start-max",
-					"Start max", "TODO",
+					"Start max", "A timespan such that only events that are within the timespan are returned.",
 					G_TYPE_TIME_VAL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
-	g_object_class_install_property (gobject_class, PROP_CTZ,
-				g_param_spec_string ("ctz",
-					"CTZ", "TODO",
+
+	/**
+	 * GDataCalendarQuery:timezone:
+	 *
+	 * The current timezone. If not specified, times are returned in UTC.
+	 **/
+	g_object_class_install_property (gobject_class, PROP_TIMEZONE,
+				g_param_spec_string ("timezone",
+					"Timezone", "The current timezone. If not specified, times are returned in UTC.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 }
@@ -134,7 +210,7 @@ gdata_calendar_query_finalize (GObject *object)
 
 	g_free (priv->order_by);
 	g_free (priv->sort_order);
-	g_free (priv->ctz);
+	g_free (priv->timezone);
 
 	/* Chain up to the parent class */
 	G_OBJECT_CLASS (gdata_calendar_query_parent_class)->finalize (object);
@@ -170,8 +246,8 @@ gdata_calendar_query_get_property (GObject *object, guint property_id, GValue *v
 		case PROP_START_MAX:
 			g_value_set_boxed (value, &(priv->start_max));
 			break;
-		case PROP_CTZ:
-			g_value_set_string (value, priv->ctz);
+		case PROP_TIMEZONE:
+			g_value_set_string (value, priv->timezone);
 			break;
 		default:
 			/* We don't have any other property... */
@@ -210,8 +286,8 @@ gdata_calendar_query_set_property (GObject *object, guint property_id, const GVa
 		case PROP_START_MAX:
 			gdata_calendar_query_set_start_max (self, g_value_get_boxed (value));
 			break;
-		case PROP_CTZ:
-			gdata_calendar_query_set_ctz (self, g_value_get_string (value));
+		case PROP_TIMEZONE:
+			gdata_calendar_query_set_timezone (self, g_value_get_string (value));
 			break;
 		default:
 			/* We don't have any other property... */
@@ -220,12 +296,31 @@ gdata_calendar_query_set_property (GObject *object, guint property_id, const GVa
 	}
 }
 
+/**
+ * gdata_calendar_query_new:
+ * @q: a query string
+ *
+ * Creates a new #GDataCalendarQuery with its #GDataQuery:q property set to @q.
+ *
+ * Return value: a new #GDataCalendarQuery
+ **/
 GDataCalendarQuery *
 gdata_calendar_query_new (const gchar *q)
 {
 	return g_object_new (GDATA_TYPE_CALENDAR_QUERY, "q", q, NULL);
 }
 
+/**
+ * gdata_calendar_query_new_with_limits:
+ * @q: a query string
+ * @start_min: a starting time for the event period
+ * @start_max: an ending time for the event period
+ *
+ * Creates a new #GDataCalendarQuery with its #GDataQuery:q property set to @q, and the time limits @start_min and @start_max
+ * applied.
+ *
+ * Return value: a new #GDataCalendarQuery
+ **/
 GDataCalendarQuery *
 gdata_calendar_query_new_with_limits (const gchar *q, GTimeVal *start_min, GTimeVal *start_max)
 {
@@ -236,6 +331,14 @@ gdata_calendar_query_new_with_limits (const gchar *q, GTimeVal *start_min, GTime
 			     NULL);
 }
 
+/**
+ * gdata_calendar_query_get_future_events:
+ * @self: a #GDataCalendarQuery
+ *
+ * Gets the #GDataCalendarQuery:future-events property.
+ *
+ * Return value: the future events property
+ **/
 gboolean
 gdata_calendar_query_get_future_events (GDataCalendarQuery *self)
 {
@@ -243,6 +346,13 @@ gdata_calendar_query_get_future_events (GDataCalendarQuery *self)
 	return self->priv->future_events;
 }
 
+/**
+ * gdata_calendar_query_set_future_events:
+ * @self: a #GDataCalendarQuery
+ * @future_events: %TRUE to unconditionally show future events, %FALSE otherwise
+ *
+ * Sets the #GDataCalendarQuery:future-events property of the #GDataCalendarQuery to @future_events.
+ **/
 void
 gdata_calendar_query_set_future_events (GDataCalendarQuery *self, gboolean future_events)
 {
@@ -251,6 +361,14 @@ gdata_calendar_query_set_future_events (GDataCalendarQuery *self, gboolean futur
 	g_object_notify (G_OBJECT (self), "future-events");
 }
 
+/**
+ * gdata_calendar_query_get_order_by:
+ * @self: a #GDataCalendarQuery
+ *
+ * Gets the #GDataCalendarQuery:order-by property.
+ *
+ * Return value: the order by property, or %NULL if it is unset
+ **/
 const gchar *
 gdata_calendar_query_get_order_by (GDataCalendarQuery *self)
 {
@@ -258,6 +376,15 @@ gdata_calendar_query_get_order_by (GDataCalendarQuery *self)
 	return self->priv->order_by;
 }
 
+/**
+ * gdata_calendar_query_set_order_by:
+ * @self: a #GDataCalendarQuery
+ * @order_by: a new order by string, or %NULL
+ *
+ * Sets the #GDataCalendarQuery:order-by property of the #GDataCalendarQuery to the new order by string, @order_by.
+ *
+ * Set @order_by to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_calendar_query_set_order_by (GDataCalendarQuery *self, const gchar *order_by)
 {
@@ -268,6 +395,14 @@ gdata_calendar_query_set_order_by (GDataCalendarQuery *self, const gchar *order_
 	g_object_notify (G_OBJECT (self), "order-by");
 }
 
+/**
+ * gdata_calendar_query_get_recurrence_expansion_start:
+ * @self: a #GDataCalendarQuery
+ * @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.
+ **/
 void
 gdata_calendar_query_get_recurrence_expansion_start (GDataCalendarQuery *self, GTimeVal *start)
 {
@@ -276,15 +411,39 @@ gdata_calendar_query_get_recurrence_expansion_start (GDataCalendarQuery *self, G
 	*start = self->priv->recurrence_expansion_start;
 }
 
+/**
+ * gdata_calendar_query_set_recurrence_expansion_start:
+ * @self: a #GDataCalendarQuery
+ * @start: a new start time
+ *
+ * Sets the #GDataCalendarQuery:recurrence-expansion-start property of the #GDataCalendarQuery
+ * to the new time/date, @start.
+ *
+ * Set @start to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_calendar_query_set_recurrence_expansion_start (GDataCalendarQuery *self, GTimeVal *start)
 {
 	g_return_if_fail (GDATA_IS_CALENDAR_QUERY (self));
-	g_return_if_fail (start != NULL);
-	self->priv->recurrence_expansion_start = *start;
+
+	if (start == NULL) {
+		self->priv->recurrence_expansion_start.tv_sec = 0;
+		self->priv->recurrence_expansion_start.tv_usec = 0;
+	} else {
+		self->priv->recurrence_expansion_start = *start;
+	}
+
 	g_object_notify (G_OBJECT (self), "recurrence-expansion-start");
 }
 
+/**
+ * gdata_calendar_query_get_recurrence_expansion_end:
+ * @self: a #GDataCalendarQuery
+ * @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.
+ **/
 void
 gdata_calendar_query_get_recurrence_expansion_end (GDataCalendarQuery *self, GTimeVal *end)
 {
@@ -293,15 +452,39 @@ gdata_calendar_query_get_recurrence_expansion_end (GDataCalendarQuery *self, GTi
 	*end = self->priv->recurrence_expansion_end;
 }
 
+/**
+ * gdata_calendar_query_set_recurrence_expansion_end:
+ * @self: a #GDataCalendarQuery
+ * @end: a new end time
+ *
+ * Sets the #GDataCalendarQuery:recurrence-expansion-end property of the #GDataCalendarQuery
+ * to the new time/date, @end.
+ *
+ * Set @end to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_calendar_query_set_recurrence_expansion_end (GDataCalendarQuery *self, GTimeVal *end)
 {
 	g_return_if_fail (GDATA_IS_CALENDAR_QUERY (self));
-	g_return_if_fail (end != NULL);
-	self->priv->recurrence_expansion_end = *end;
+
+	if (end == NULL) {
+		self->priv->recurrence_expansion_end.tv_sec = 0;
+		self->priv->recurrence_expansion_end.tv_usec = 0;
+	} else {
+		self->priv->recurrence_expansion_end = *end;
+	}
+
 	g_object_notify (G_OBJECT (self), "recurrence-expansion-end");
 }
 
+/**
+ * gdata_calendar_query_get_single_events:
+ * @self: a #GDataCalendarQuery
+ *
+ * Gets the #GDataCalendarQuery:single-events property.
+ *
+ * Return value: the single events property
+ **/
 gboolean
 gdata_calendar_query_get_single_events (GDataCalendarQuery *self)
 {
@@ -309,6 +492,13 @@ gdata_calendar_query_get_single_events (GDataCalendarQuery *self)
 	return self->priv->single_events;
 }
 
+/**
+ * gdata_calendar_query_set_single_events:
+ * @self: a #GDataCalendarQuery
+ * @single_events: %TRUE to show recurring events as single events, %FALSE otherwise
+ *
+ * Sets the #GDataCalendarQuery:single-events property of the #GDataCalendarQuery to @single_events.
+ **/
 void
 gdata_calendar_query_set_single_events (GDataCalendarQuery *self, gboolean single_events)
 {
@@ -317,6 +507,14 @@ gdata_calendar_query_set_single_events (GDataCalendarQuery *self, gboolean singl
 	g_object_notify (G_OBJECT (self), "single-events");
 }
 
+/**
+ * gdata_calendar_query_get_sort_order:
+ * @self: a #GDataCalendarQuery
+ *
+ * Gets the #GDataCalendarQuery:sort-order property.
+ *
+ * Return value: the sort order property, or %NULL if it is unset
+ **/
 const gchar *
 gdata_calendar_query_get_sort_order (GDataCalendarQuery *self)
 {
@@ -324,6 +522,15 @@ gdata_calendar_query_get_sort_order (GDataCalendarQuery *self)
 	return self->priv->sort_order;
 }
 
+/**
+ * gdata_calendar_query_set_sort_order:
+ * @self: a #GDataCalendarQuery
+ * @sort_order: a new sort order string, or %NULL
+ *
+ * Sets the #GDataCalendarQuery:sort-order property of the #GDataCalendarQuery to the new sort order string, @sort_order.
+ *
+ * Set @sort_order to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_calendar_query_set_sort_order (GDataCalendarQuery *self, const gchar *sort_order)
 {
@@ -334,6 +541,14 @@ gdata_calendar_query_set_sort_order (GDataCalendarQuery *self, const gchar *sort
 	g_object_notify (G_OBJECT (self), "sort-order");
 }
 
+/**
+ * gdata_calendar_query_get_start_min:
+ * @self: a #GDataCalendarQuery
+ * @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.
+ **/
 void
 gdata_calendar_query_get_start_min (GDataCalendarQuery *self, GTimeVal *start_min)
 {
@@ -342,20 +557,39 @@ gdata_calendar_query_get_start_min (GDataCalendarQuery *self, GTimeVal *start_mi
 	*start_min = self->priv->start_min;
 }
 
+/**
+ * gdata_calendar_query_set_start_min:
+ * @self: a #GDataCalendarQuery
+ * @start_min: a new minimum start time
+ *
+ * Sets the #GDataCalendarQuery:start-min property of the #GDataCalendarQuery
+ * to the new time/date, @start_min.
+ *
+ * Set @start_min to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_calendar_query_set_start_min (GDataCalendarQuery *self, GTimeVal *start_min)
 {
 	g_return_if_fail (GDATA_IS_CALENDAR_QUERY (self));
 
 	if (start_min == NULL) {
-		self->priv->start_min_set = FALSE; /* TODO: got to be a better way than this */
-		return;
+		self->priv->start_min.tv_sec = 0;
+		self->priv->start_min.tv_usec = 0;
+	} else {
+		self->priv->start_min = *start_min;
 	}
-	self->priv->start_min_set = TRUE;
-	self->priv->start_min = *start_min;
+
 	g_object_notify (G_OBJECT (self), "start-min");
 }
 
+/**
+ * gdata_calendar_query_get_start_max:
+ * @self: a #GDataCalendarQuery
+ * @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.
+ **/
 void
 gdata_calendar_query_get_start_max (GDataCalendarQuery *self, GTimeVal *start_max)
 {
@@ -364,33 +598,61 @@ gdata_calendar_query_get_start_max (GDataCalendarQuery *self, GTimeVal *start_ma
 	*start_max = self->priv->start_max;
 }
 
+/**
+ * gdata_calendar_query_set_start_max:
+ * @self: a #GDataCalendarQuery
+ * @start_max: a new maximum start time
+ *
+ * Sets the #GDataCalendarQuery:start-max property of the #GDataCalendarQuery
+ * to the new time/date, @start_max.
+ *
+ * Set @start_max to %NULL to unset the property in the query URI.
+ **/
 void
 gdata_calendar_query_set_start_max (GDataCalendarQuery *self, GTimeVal *start_max)
 {
 	g_return_if_fail (GDATA_IS_CALENDAR_QUERY (self));
 
 	if (start_max == NULL) {
-		self->priv->start_max_set = FALSE; /* TODO: got to be a better way than this */
-		return;
+		self->priv->start_max.tv_sec = 0;
+		self->priv->start_max.tv_usec = 0;
+	} else {
+		self->priv->start_max = *start_max;
 	}
-	self->priv->start_max_set = TRUE;
-	self->priv->start_max = *start_max;
+
 	g_object_notify (G_OBJECT (self), "start-max");
 }
 
+/**
+ * gdata_calendar_query_get_timezone:
+ * @self: a #GDataCalendarQuery
+ *
+ * Gets the #GDataCalendarQuery:timezone property.
+ *
+ * Return value: the timezone property, or %NULL if it is unset
+ **/
 const gchar *
-gdata_calendar_query_get_ctz (GDataCalendarQuery *self)
+gdata_calendar_query_get_timezone (GDataCalendarQuery *self)
 {
 	g_return_val_if_fail (GDATA_IS_CALENDAR_QUERY (self), NULL);
-	return self->priv->ctz;
+	return self->priv->timezone;
 }
 
+/**
+ * gdata_calendar_query_set_timezone:
+ * @self: a #GDataCalendarQuery
+ * @_timezone: a new timezone string, or %NULL
+ *
+ * Sets the #GDataCalendarQuery:timezone property of the #GDataCalendarQuery to the new timezone string, @timezone.
+ *
+ * Set @timezone to %NULL to unset the property in the query URI.
+ **/
 void
-gdata_calendar_query_set_ctz (GDataCalendarQuery *self, const gchar *ctz)
+gdata_calendar_query_set_timezone (GDataCalendarQuery *self, const gchar *_timezone)
 {
 	g_return_if_fail (GDATA_IS_CALENDAR_QUERY (self));
 
-	g_free (self->priv->ctz);
-	self->priv->ctz = g_strdup (ctz);
-	g_object_notify (G_OBJECT (self), "ctz");
+	g_free (self->priv->timezone);
+	self->priv->timezone = g_strdup (_timezone);
+	g_object_notify (G_OBJECT (self), "timezone");
 }
diff --git a/gdata/services/calendar/gdata-calendar-query.h b/gdata/services/calendar/gdata-calendar-query.h
index 102cccf..aa9f892 100644
--- a/gdata/services/calendar/gdata-calendar-query.h
+++ b/gdata/services/calendar/gdata-calendar-query.h
@@ -37,12 +37,23 @@ G_BEGIN_DECLS
 
 typedef struct _GDataCalendarQueryPrivate	GDataCalendarQueryPrivate;
 
+/**
+ * GDataCalendarQuery:
+ *
+ * All the fields in the #GDataCalendarQuery structure are private and should never be accessed directly.
+ **/
 typedef struct {
 	GDataQuery parent;
 	GDataCalendarQueryPrivate *priv;
 } GDataCalendarQuery;
 
+/**
+ * GDataCalendarQueryClass:
+ *
+ * All the fields in the #GDataCalendarQueryClass structure are private and should never be accessed directly.
+ **/
 typedef struct {
+	/*< private >*/
 	GDataQueryClass parent;
 } GDataCalendarQueryClass;
 
@@ -67,8 +78,8 @@ void gdata_calendar_query_get_start_min (GDataCalendarQuery *self, GTimeVal *sta
 void gdata_calendar_query_set_start_min (GDataCalendarQuery *self, GTimeVal *start_min);
 void gdata_calendar_query_get_start_max (GDataCalendarQuery *self, GTimeVal *start_max);
 void gdata_calendar_query_set_start_max (GDataCalendarQuery *self, GTimeVal *start_max);
-const gchar *gdata_calendar_query_get_ctz (GDataCalendarQuery *self);
-void gdata_calendar_query_set_ctz (GDataCalendarQuery *self, const gchar *ctz);
+const gchar *gdata_calendar_query_get_timezone (GDataCalendarQuery *self);
+void gdata_calendar_query_set_timezone (GDataCalendarQuery *self, const gchar *_timezone);
 
 G_END_DECLS
 
diff --git a/gdata/services/calendar/gdata-calendar-service.c b/gdata/services/calendar/gdata-calendar-service.c
index 76b73d1..18b566e 100644
--- a/gdata/services/calendar/gdata-calendar-service.c
+++ b/gdata/services/calendar/gdata-calendar-service.c
@@ -17,6 +17,19 @@
  * License along with GData Client.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gdata-calendar-service
+ * @short_description: GData Calendar service object
+ * @stability: Unstable
+ * @include: gdata/services/calendar/gdata-calendar-service.h
+ *
+ * #GDataCalendarService is a subclass of #GDataService for communicating with the GData API of Google Calendar. It supports querying
+ * for, inserting, editing and deleting events from calendars, as well as operations on the calendars themselves.
+ *
+ * For more details of Google Calendar's GData API, see the <ulink type="http" url="http://code.google.com/apis/calendar/docs/2.0/reference.html";>
+ * online documentation</ulink>.
+ **/
+
 #include <config.h>
 #include <glib.h>
 #include <glib/gi18n-lib.h>
@@ -46,6 +59,14 @@ gdata_calendar_service_init (GDataCalendarService *self)
 	/* Nothing to see here */
 }
 
+/**
+ * gdata_calendar_service_new:
+ * @client_id: your application's client ID
+ *
+ * Creates a new #GDataCalendarService. The @client_id must be unique for your application, and as registered with Google.
+ *
+ * Return value: a new #GDataCalendarService, or %NULL
+ **/
 GDataCalendarService *
 gdata_calendar_service_new (const gchar *client_id)
 {
@@ -56,6 +77,23 @@ gdata_calendar_service_new (const gchar *client_id)
 			     NULL);
 }
 
+/**
+ * gdata_calendar_service_query_all_calendars:
+ * @self: a #GDataCalendarService
+ * @query: a #GDataCalendarQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @error: a #GError, or %NULL
+ *
+ * Queries the service to return a list of all calendars from the authenticated account which match the given
+ * @query. It will return all calendars the user has read access to, including primary, secondary and imported
+ * calendars.
+ *
+ * For more details, see gdata_service_query().
+ *
+ * Return value: a #GDataFeed of query results; unref with g_object_unref()
+ **/
 GDataFeed *
 gdata_calendar_service_query_all_calendars (GDataCalendarService *self, GDataCalendarQuery *query, GCancellable *cancellable,
 					    GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error)
@@ -71,6 +109,23 @@ gdata_calendar_service_query_all_calendars (GDataCalendarService *self, GDataCal
 				    GDATA_TYPE_CALENDAR_CALENDAR, cancellable, progress_callback, progress_user_data, error);
 }
 
+/**
+ * gdata_calendar_service_query_all_calendars_async:
+ * @self: a #GDataCalendarService
+ * @query: a #GDataCalendarQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @callback: a #GAsyncReadyCallback to call when authentication is finished
+ * @user_data: data to pass to the @callback function
+ *
+ * Queries the service to return a list of all calendars from the authenticated account which match the given
+ * @query. @self and @query are all reffed when this function is called, so can safely be unreffed after
+ * this function returns.
+ *
+ * For more details, see gdata_calendar_service_query_all_calendars(), which is the synchronous version of
+ * this function, and gdata_service_query_async(), which is the base asynchronous query function.
+ **/
 void
 gdata_calendar_service_query_all_calendars_async (GDataCalendarService *self, GDataCalendarQuery *query, GCancellable *cancellable,
 						  GDataQueryProgressCallback progress_callback, gpointer progress_user_data,
@@ -88,6 +143,23 @@ gdata_calendar_service_query_all_calendars_async (GDataCalendarService *self, GD
 				   GDATA_TYPE_CALENDAR_CALENDAR, cancellable, progress_callback, progress_user_data, callback, user_data);
 }
 
+/**
+ * gdata_calendar_service_query_own_calendars:
+ * @self: a #GDataCalendarService
+ * @query: a #GDataCalendarQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @error: a #GError, or %NULL
+ *
+ * Queries the service to return a list of calendars from the authenticated account which match the given
+ * @query, and the authenticated user owns. (i.e. They have full read/write access to the calendar, as well
+ * as the ability to set permissions on the calendar.)
+ *
+ * For more details, see gdata_service_query().
+ *
+ * Return value: a #GDataFeed of query results; unref with g_object_unref()
+ **/
 GDataFeed *
 gdata_calendar_service_query_own_calendars (GDataCalendarService *self, GDataCalendarQuery *query, GCancellable *cancellable,
 					    GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error)
@@ -103,6 +175,23 @@ gdata_calendar_service_query_own_calendars (GDataCalendarService *self, GDataCal
 				    GDATA_TYPE_CALENDAR_CALENDAR, cancellable, progress_callback, progress_user_data, error);
 }
 
+/**
+ * gdata_calendar_service_query_own_calendars_async:
+ * @self: a #GDataCalendarService
+ * @query: a #GDataCalendarQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @callback: a #GAsyncReadyCallback to call when authentication is finished
+ * @user_data: data to pass to the @callback function
+ *
+ * Queries the service to return a list of calendars from the authenticated account which match the given
+ * @query, and the authenticated user owns. @self and @query are all reffed when this function is called,
+ * so can safely be unreffed after this function returns.
+ *
+ * For more details, see gdata_calendar_service_query_own_calendars(), which is the synchronous version of
+ * this function, and gdata_service_query_async(), which is the base asynchronous query function.
+ **/
 void
 gdata_calendar_service_query_own_calendars_async (GDataCalendarService *self, GDataCalendarQuery *query, GCancellable *cancellable,
 						  GDataQueryProgressCallback progress_callback, gpointer progress_user_data,
@@ -120,11 +209,27 @@ gdata_calendar_service_query_own_calendars_async (GDataCalendarService *self, GD
 				   GDATA_TYPE_CALENDAR_CALENDAR, cancellable, progress_callback, progress_user_data, callback, user_data);
 }
 
-/* TODO: Async variant */
+/**
+ * gdata_calendar_service_query_events:
+ * @self: a #GDataCalendarService
+ * @calendar: a #GDataCalendarCalendar
+ * @query: a #GDataCalendarQuery with the query parameters, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @progress_callback: a #GDataQueryProgressCallback to call when an entry is loaded, or %NULL
+ * @progress_user_data: data to pass to the @progress_callback function
+ * @error: a #GError, or %NULL
+ *
+ * Queries the service to return a list of events in the given @calendar, which match @query.
+ *
+ * For more details, see gdata_service_query().
+ *
+ * Return value: a #GDataFeed of query results; unref with g_object_unref()
+ **/
 GDataFeed *
 gdata_calendar_service_query_events (GDataCalendarService *self, GDataCalendarCalendar *calendar, GDataCalendarQuery *query, GCancellable *cancellable,
 				     GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error)
 {
+	/* TODO: Async variant */
 	const gchar *uri;
 
 	/* Ensure we're authenticated first */
@@ -148,10 +253,24 @@ gdata_calendar_service_query_events (GDataCalendarService *self, GDataCalendarCa
 				    progress_callback, progress_user_data, error);
 }
 
-/* TODO: Async variant */
+/**
+ * gdata_calendar_service_insert_event:
+ * @self: a #GDataCalendarService
+ * @event: the #GDataCalendarEvent to insert
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Inserts @event by uploading it to the online calendar service.
+ *
+ * For more details, see gdata_service_insert_entry().
+ *
+ * Return value: an updated #GDataCalendarEvent, or %NULL
+ **/
 GDataCalendarEvent *
 gdata_calendar_service_insert_event (GDataCalendarService *self, GDataCalendarEvent *event, GCancellable *cancellable, GError **error)
 {
+	/* TODO: Async variant */
+	/* TODO: How do we choose which calendar? */
 	gchar *uri;
 	GDataEntry *entry;
 
diff --git a/gdata/services/calendar/gdata-calendar-service.h b/gdata/services/calendar/gdata-calendar-service.h
index 263013d..d69a287 100644
--- a/gdata/services/calendar/gdata-calendar-service.h
+++ b/gdata/services/calendar/gdata-calendar-service.h
@@ -37,11 +37,22 @@ G_BEGIN_DECLS
 
 typedef struct _GDataCalendarServicePrivate	GDataCalendarServicePrivate;
 
+/**
+ * GDataCalendarService:
+ *
+ * All the fields in the #GDataCalendarService structure are private and should never be accessed directly.
+ **/
 typedef struct {
 	GDataService parent;
 } GDataCalendarService;
 
+/**
+ * GDataCalendarServiceClass:
+ *
+ * All the fields in the #GDataCalendarServiceClass structure are private and should never be accessed directly.
+ **/
 typedef struct {
+	/*< private >*/
 	GDataServiceClass parent;
 } GDataCalendarServiceClass;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]