various - doc for icalproperty_get_datetime_with_component()

4 files changed, 33 insertions, 3 deletions

diff --git a/src/libical-glib/api/i-cal-component.xml b/src/libical-glib/api/i-cal-component.xml
index c6b6983d..2bd4c05e 100644
--- a/src/libical-glib/api/i-cal-component.xml
+++ b/src/libical-glib/api/i-cal-component.xml
@@ -94,6 +94,14 @@
         <parameter type="ICalComponent *" name="component" annotation="nullable" comment="An #ICalComponent."/>
         <comment xml:space="preserve">Set the parent #ICalComponent of the specified #ICalProperty.</comment>
     </method>
+    <method name="i_cal_property_get_datetime_with_component" corresponds="icalproperty_get_datetime_with_component" kind="get" since="3.0.5">
+        <parameter type="ICalProperty *" name="prop" comment="An #ICalProperty."/>
+        <parameter type="ICalComponent *" name="comp" annotation="nullable" comment="An #ICalComponent."/>
+        <returns type="ICalTime *" annotation="transfer full" comment="Get a DATE or DATE-TIME property as an #ICalTime."/>
+        <comment xml:space="preserve">If the property is a DATE-TIME with a TZID parameter and a corresponding VTIMEZONE is present in the component, the returned component will already be in the correct timezone; otherwise the caller is responsible for converting it.
+ *
+ * The @comp can be NULL, in which case the parent of the @prop is used to find the corresponding time zone.</comment>
+    </method>
     <method name="i_cal_component_get_current_property" corresponds="icalcomponent_get_current_property" since="1.0">
         <parameter type="ICalComponent *" name="component" comment="A #ICalComponent."/>
         <returns type="ICalProperty *" annotation="transfer full" translator_argus="(GObject *)component" comment="The current #ICalProperty."/>
diff --git a/src/libical/icalcomponent.h b/src/libical/icalcomponent.h
index f336abb7..dbedf08e 100644
--- a/src/libical/icalcomponent.h
+++ b/src/libical/icalcomponent.h
@@ -287,7 +287,13 @@ LIBICAL_ICAL_EXPORT void icalcomponent_foreach_recurrence(icalcomponent *comp,
 LIBICAL_ICAL_EXPORT void icalcomponent_normalize(icalcomponent *comp);
 
 /*
- * Returns the datetime corresponding to the specified @p icalproperty and @p icalcomponent.
+ * Computes the datetime corresponding to the specified @p icalproperty and @p icalcomponent.
+ * If the property is a DATE-TIME with a TZID parameter and a corresponding VTIMEZONE
+ * is present in the component, the returned component will already be in the correct
+ * timezone; otherwise the caller is responsible for converting it.
+ *
+ * Call icaltime_is_null_time() on the returned value to detect failures.
+ *
  * @since 3.0.5
  */
 LIBICAL_ICAL_EXPORT struct icaltimetype icalproperty_get_datetime_with_component(
diff --git a/src/libical/icalproperty.c b/src/libical/icalproperty.c
index 86704645..e1451df9 100644
--- a/src/libical/icalproperty.c
+++ b/src/libical/icalproperty.c
@@ -1074,8 +1074,6 @@ void icalproperty_normalize(icalproperty *prop)
  *
  *      The @a comp can be NULL, in which case the parent of the @a prop
  *      is used to find the corresponding time zone.
- *
- *      FIXME this is useless until we can flag the failure
  */
 struct icaltimetype icalproperty_get_datetime_with_component(icalproperty *prop,
                                                              icalcomponent *comp)
diff --git a/src/test/libical-glib/component.py b/src/test/libical-glib/component.py
index f8e9981c..870589be 100755
--- a/src/test/libical-glib/component.py
+++ b/src/test/libical-glib/component.py
@@ -302,5 +302,23 @@ def main():
     comp.foreach_recurrence(ICalGLib.Time.from_string("20180321T000000Z"), ICalGLib.Time.from_string("20180323T235959Z"), foreachRecurrenceCb, counter)
     assert counter.counter == 3
 
+    comp = ICalGLib.Component.new_from_string(event_str1);
+    prop = comp.get_first_property(ICalGLib.PropertyKind.DTSTART_PROPERTY)
+    prop.remove_parameter_by_kind(ICalGLib.ParameterKind.TZID_PARAMETER)
+    tz = ICalGLib.Timezone.get_builtin_timezone("Europe/Prague")
+    prop.set_parameter(ICalGLib.Parameter.new_tzid(tz.get_tzid()))
+
+    itt = prop.get_datetime_with_component(comp)
+    assert itt.get_timezone() != None
+    assert itt.get_timezone().get_location() == "Europe/Prague"
+
+    itt = prop.get_datetime_with_component(None)
+    assert itt.get_timezone() != None
+    assert itt.get_timezone().get_location() == "Europe/Prague"
+
+    itt = comp.get_dtstart()
+    assert itt.get_timezone() != None
+    assert itt.get_timezone().get_location() == "Europe/Prague"
+
 if __name__ == "__main__":
     main()