[gnome-calendar/gnome-3-28] event: improve documentation for gcal_event_is_multiday

[Georges Basile Stavracas Neto <gbsneto src gnome org>]

commit 9c00ca1d4461fdf7c75671c869fd72cd816b5ca1
Author: Georges Basile Stavracas Neto <georges stavracas gmail com>
Date:   Mon Apr 30 20:45:01 2018 -0300

    event: improve documentation for gcal_event_is_multiday
    
    Add some examples, so I can remember them in a few days from
    now.

 src/gcal-event.c | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)
---
diff --git a/src/gcal-event.c b/src/gcal-event.c
index 738bca7f..5f64e6f9 100644
--- a/src/gcal-event.c
+++ b/src/gcal-event.c
@@ -1492,7 +1492,19 @@ gcal_event_get_uid (GcalEvent *self)
  * gcal_event_is_multiday:
  * @self: a #GcalEvent
  *
- * Whether the event spans more than 1 day.
+ * Whether the event visibly spans more than one day in the
+ * calendar.
+ *
+ * This function can return different values for the same event
+ * depending on your timezone. For example, an event that spans
+ * [ 02:00, 22:00 ) +0000 would assume the following values:
+ *
+ * |[
+ *             D-1            D            D+1
+ * -0600 [         ---][-------     ][            ] (multiday)
+ * +0000 [            ][ ---------- ][            ] (single day)
+ * +0800 [            ][     -------][---         ] (multiday)
+ * ]|
  *
  * Returns: %TRUE if @self spans more than 1 day, %FALSE otherwise.
  */