[libgdata/libgdata-0-14: 5/18] calendar: Document mutual exclusion between event times and recurrences

[Philip Withnall <pwithnall src gnome org>]

commit 3c7551b2ccce59412180ac969b8ce027c7c05783
Author: Philip Withnall <philip tecnocode co uk>
Date:   Fri Aug 30 23:40:23 2013 -0600

    calendar: Document mutual exclusion between event times and recurrences
    
    Turns out the server explicitly disallows setting individual times for
    an event if it has a recurrence rule set (and vice-versa). It’s not
    possible to add checks for this in libgdata without breaking API, so
    rely on the server to fail to insert the offending GDataCalendarEvent
    if it pleases.
    
    Spotted by Miao Yu <will yu aol com>.

 gdata/services/calendar/gdata-calendar-event.c |   14 ++++++++++++++
 1 files changed, 14 insertions(+), 0 deletions(-)
---
diff --git a/gdata/services/calendar/gdata-calendar-event.c b/gdata/services/calendar/gdata-calendar-event.c
index 81b91ab..ed8c554 100644
--- a/gdata/services/calendar/gdata-calendar-event.c
+++ b/gdata/services/calendar/gdata-calendar-event.c
@@ -306,6 +306,9 @@ gdata_calendar_event_class_init (GDataCalendarEventClass *klass)
         * For more information, see the <ulink type="http" 
url="http://code.google.com/apis/gdata/elements.html#gdRecurrence";>
         * GData specification</ulink>.
         *
+        * Note: gdata_calendar_event_add_time() and gdata_calendar_event_set_recurrence() are mutually
+        * exclusive. See the documentation for gdata_calendar_event_add_time() for details.
+        *
         * Since: 0.3.0
         **/
        g_object_class_install_property (gobject_class, PROP_RECURRENCE,
@@ -1088,6 +1091,14 @@ gdata_calendar_event_get_places (GDataCalendarEvent *self)
  *
  * Duplicate times will not be added to the list.
  *
+ * Note: gdata_calendar_event_add_time() and gdata_calendar_event_set_recurrence() are mutually
+ * exclusive, as the server doesn't support positive exceptions to recurrence rules. If recurrences
+ * are required, use gdata_calendar_event_set_recurrence(). Note that this means reminders cannot
+ * be set for the event, as they are only supported by #GDataGDWhen. No checks are performed for
+ * these forbidden conditions, as to do so would break libgdata's API; if both a recurrence is set
+ * and a specific time is added, the server will return an error when the #GDataCalendarEvent is
+ * inserted using gdata_service_insert_entry().
+ *
  * Since: 0.2.0
  **/
 void
@@ -1181,6 +1192,9 @@ gdata_calendar_event_get_recurrence (GDataCalendarEvent *self)
  *
  * Set @recurrence to %NULL to unset the property in the event.
  *
+ * Note: gdata_calendar_event_add_time() and gdata_calendar_event_set_recurrence() are mutually
+ * exclusive. See the documentation for gdata_calendar_event_add_time() for details.
+ *
  * Since: 0.3.0
  **/
 void