Unify all visible docstrings to .h files

Reduces redundancy and conflicting information

16 files changed, 574 insertions, 594 deletions

diff --git a/src/libical/icalcomponent.c b/src/libical/icalcomponent.c
index 624e819d..421d265d 100644
--- a/src/libical/icalcomponent.c
+++ b/src/libical/icalcomponent.c
@@ -108,15 +108,11 @@ static icalcomponent *icalcomponent_new_impl(icalcomponent_kind kind)
     return comp;
 }
 
-/** @brief Constructor
- */
 icalcomponent *icalcomponent_new(icalcomponent_kind kind)
 {
     return icalcomponent_new_impl(kind);
 }
 
-/** @brief Constructor
- */
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wvarargs"
 icalcomponent *icalcomponent_vanew(icalcomponent_kind kind, ...)
@@ -137,15 +133,11 @@ icalcomponent *icalcomponent_vanew(icalcomponent_kind kind, ...)
 }
 #pragma clang diagnostic pop
 
-/** @brief Constructor
- */
 icalcomponent *icalcomponent_new_from_string(const char *str)
 {
     return icalparser_parse_string(str);
 }
 
-/** @brief Constructor
- */
 icalcomponent *icalcomponent_new_clone(icalcomponent *old)
 {
     icalcomponent *new;
@@ -174,8 +166,6 @@ icalcomponent *icalcomponent_new_clone(icalcomponent *old)
     return new;
 }
 
-/** @brief Constructor
- */
 icalcomponent *icalcomponent_new_x(const char *x_name)
 {
     icalcomponent *comp = icalcomponent_new_impl(ICAL_X_COMPONENT);
@@ -187,8 +177,6 @@ icalcomponent *icalcomponent_new_x(const char *x_name)
     return comp;
 }
 
-/*** @brief Destructor
- */
 void icalcomponent_free(icalcomponent *c)
 {
     icalproperty *prop;
@@ -614,23 +602,6 @@ icalcomponent *icalcomponent_get_first_real_component(icalcomponent *c)
     return 0;
 }
 
-/**     @brief Gets the timespan covered by this component, in UTC.
- *
- *      see icalcomponent_foreach_recurrence() for a better way to
- *      extract spans from an component.
- *
- *      This method can be called on either a VCALENDAR or any real
- *      component. If the VCALENDAR contains no real component, but
- *      contains a VTIMEZONE, we return that span instead.
- *      This might not be a desirable behavior; we keep it for now
- *      for backward compatibility, but it might be deprecated at a
- *      future time.
- *
- *      FIXME this API needs to be clarified. DTEND is defined as the
- *      first available time after the end of this event, so the span
- *      should actually end 1 second before DTEND.
- */
-
 icaltime_span icalcomponent_get_span(icalcomponent *comp)
 {
     icalcomponent *inner;
@@ -709,29 +680,6 @@ or empty VCALENDAR component"); */
     return span;
 }
 
-/**
- * Decide if this recurrence is acceptable
- *
- * @param comp       A valid icalcomponent.
- * @param dtstart    The base dtstart value for this component.
- * @param recurtime  The time to test against.
- *
- * @return true if the recurrence value is excluded, false otherwise.
- *
- * This function decides if a specific recurrence value is
- * excluded by EXRULE or EXDATE properties.
- *
- * It's not the most efficient code.  You might get better performance
- * if you assume that recurtime is always increasing for each
- * call. Then you could:
- *
- *   - sort the EXDATE values
- *   - save the state of each EXRULE iterator for the next call.
- *
- * In this case though you don't need to worry how you call this
- * function.  It will always return the correct result.
- */
-
 int icalproperty_recurrence_is_excluded(icalcomponent *comp,
                                         struct icaltimetype *dtstart,
                                         struct icaltimetype *recurtime)
@@ -803,7 +751,6 @@ int icalproperty_recurrence_is_excluded(icalcomponent *comp,
  *
  * @return 1 if the event is a busy item, 0 if it is not.
  */
-
 static int icalcomponent_is_busy(icalcomponent *comp)
 {
     icalproperty *transp;
@@ -848,25 +795,6 @@ static int icalcomponent_is_busy(icalcomponent *comp)
     return (ret);
 }
 
-/**
- * @brief Cycles through all recurrences of an event
- *
- * @param comp           A valid VEVENT component
- * @param start          Ignore timespans before this
- * @param end            Ignore timespans after this
- * @param callback       Function called for each timespan within the range
- * @param callback_data  Pointer passed back to the callback function
- *
- * This function will call the specified callback function for once
- * for the base value of DTSTART, and foreach recurring date/time
- * value.
- *
- * It will filter out events that are specified as an EXDATE or an EXRULE.
- *
- * @todo We do not filter out duplicate RRULES/RDATES
- * @todo We do not handle RDATEs with explicit periods
- */
-
 void icalcomponent_foreach_recurrence(icalcomponent *comp,
                                       struct icaltimetype start,
                                       struct icaltimetype end,
@@ -1030,12 +958,6 @@ int icalcomponent_check_restrictions(icalcomponent *comp)
     return icalrestriction_check(comp);
 }
 
-/** @brief Returns the number of errors encountered parsing the data
- *
- * This function counts the number times the X-LIC-ERROR occurs
- * in the data structure.
- */
-
 int icalcomponent_count_errors(icalcomponent *component)
 {
     int errors = 0;
@@ -1362,9 +1284,6 @@ icalcomponent *icalcomponent_get_inner(icalcomponent *comp)
     }
 }
 
-/** @brief Sets the METHOD property to the given method
- */
-
 void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method)
 {
     icalproperty *prop = icalcomponent_get_first_property(comp, ICAL_METHOD_PROPERTY);
@@ -1377,9 +1296,6 @@ void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method)
     icalproperty_set_method(prop, method);
 }
 
-/** @brief Returns the METHOD property
- */
-
 icalproperty_method icalcomponent_get_method(icalcomponent *comp)
 {
     icalproperty *prop = icalcomponent_get_first_property(comp, ICAL_METHOD_PROPERTY);
@@ -1402,11 +1318,6 @@ if (inner == 0) { \
 } \
 prop = icalcomponent_get_first_property(inner, p_kind);
 
-/**     @brief Sets DTSTART property to given icaltime
- *
- *      This method respects the icaltime type (DATE vs DATE-TIME) and
- *      timezone (or lack thereof).
- */
 void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v)
 {
     const char *tzid;
@@ -1427,15 +1338,6 @@ void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v)
     }
 }
 
-/**     @brief Gets DTSTART property as an icaltime
- *
- *      If DTSTART is a DATE-TIME with a timezone 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.
- *
- *      FIXME this is useless until we can flag the failure
- */
 struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp)
 {
     icalcomponent *inner = icalcomponent_get_inner(comp);
@@ -1449,18 +1351,6 @@ struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp)
     return icalproperty_get_datetime_with_component(prop, comp);
 }
 
-/**     @brief Gets DTEND property as an icaltime.
- *
- *      If a DTEND property is not present but a DURATION is, we use
- *      that to determine the proper end.
- *
- *      If DTSTART is a DATE-TIME with a timezone 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.
- *
- *      FIXME this is useless until we can flag the failure
- */
 struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp)
 {
     icalcomponent *inner = icalcomponent_get_inner(comp);
@@ -1488,15 +1378,6 @@ struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp)
     return ret;
 }
 
-/**     @brief Sets DTEND property to given icaltime.
- *
- *      This method respects the icaltime type (DATE vs DATE-TIME) and
- *      timezone (or lack thereof).
- *
- *      This also checks that a DURATION property isn't already there,
- *      and returns an error if it is. It's the caller's responsibility
- *      to remove it.
- */
 void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v)
 {
     const char *tzid;
@@ -1522,15 +1403,6 @@ void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v)
     }
 }
 
-/**     @brief Sets DURATION property to given icalduration.
- *
- *      This method respects the icaltime type (DATE vs DATE-TIME) and
- *      timezone (or lack thereof).
- *
- *      This also checks that a DTEND property isn't already there,
- *      and returns an error if it is. It's the caller's responsibility
- *      to remove it.
- */
 void icalcomponent_set_duration(icalcomponent *comp, struct icaldurationtype v)
 {
     ICALSETUPSET(ICAL_DURATION_PROPERTY);
@@ -1548,11 +1420,6 @@ void icalcomponent_set_duration(icalcomponent *comp, struct icaldurationtype v)
     }
 }
 
-/**     @brief Gets DURATION property as an icalduration
- *
- *      If a DURATION property is not present but a DTEND is, we use
- *      that to determine the proper end.
- */
 struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp)
 {
     icalcomponent *inner = icalcomponent_get_inner(comp);
@@ -1989,11 +1856,6 @@ icalcomponent *icalcomponent_new_xpatch(void)
  * Timezone stuff.
  */
 
-/**
- *  This takes 2 VCALENDAR components and merges the second one into the first,
- *  resolving any problems with conflicting TZIDs. comp_to_merge will no
- *  longer exist after calling this function.
- */
 void icalcomponent_merge_component(icalcomponent *comp, icalcomponent *comp_to_merge)
 {
     icalcomponent *subcomp, *next_subcomp;
@@ -2239,9 +2101,6 @@ static void icalcomponent_rename_tzids_callback(icalparameter *param, void *data
     }
 }
 
-/**
- * @brief Calls the given function for each TZID parameter found in the component.
- */
 void icalcomponent_foreach_tzid(icalcomponent *comp,
                                 void (*callback) (icalparameter *param, void *data),
                                 void *callback_data)
@@ -2279,10 +2138,6 @@ void icalcomponent_foreach_tzid(icalcomponent *comp,
     }
 }
 
-/**
- *  @brief Returns the icaltimezone from the component corresponding to the given
- *  TZID, or NULL if the component does not have a corresponding VTIMEZONE.
- */
 icaltimezone *icalcomponent_get_timezone(icalcomponent *comp, const char *tzid)
 {
     icaltimezone *zone;
@@ -2451,14 +2306,6 @@ const char *icalcomponent_get_relcalid(icalcomponent *comp)
     return icalproperty_get_relcalid(prop);
 }
 
-/** @brief Returns the time a TODO task is DUE.
- *
- *  @param comp Valid calendar component.
- *
- *  Uses the DUE: property if it exists, otherwise we calculate the DUE
- *  value by adding the task's duration to the DTSTART time
- */
-
 struct icaltimetype icalcomponent_get_due(icalcomponent *comp)
 {
     icalcomponent *inner = icalcomponent_get_inner(comp);
@@ -2481,17 +2328,6 @@ struct icaltimetype icalcomponent_get_due(icalcomponent *comp)
     return icaltime_null_time();
 }
 
-/** @brief Sets the due date of a VTODO task.
- *
- *  @param comp Valid VTODO component.
- *  @param v    Valid due date time.
- *
- *  - If no duration or due properties then set the DUE property.
- *  - If a DUE property is already set, then reset it to the value v.
- *  - If a DURATION property is already set, then calculate the new
- *    duration based on the supplied value of v.
- */
-
 void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v)
 {
     const char *tzid;
diff --git a/src/libical/icalcomponent.h b/src/libical/icalcomponent.h
index 37dc0c04..9fbad2bb 100644
--- a/src/libical/icalcomponent.h
+++ b/src/libical/icalcomponent.h
@@ -39,16 +39,28 @@ typedef struct icalcompiter
 
 } icalcompiter;
 
+/** @brief Constructor
+ */
 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new(icalcomponent_kind kind);
 
+/** @brief Constructor
+ */
 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_clone(icalcomponent *component);
 
+/** @brief Constructor
+ */
 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_from_string(const char *str);
 
+/** @brief Constructor
+ */
 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_vanew(icalcomponent_kind kind, ...);
 
+/** @brief Constructor
+ */
 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_x(const char *x_name);
 
+/*** @brief Destructor
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_free(icalcomponent *component);
 
 LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string(icalcomponent *component);
@@ -111,9 +123,10 @@ LIBICAL_ICAL_EXPORT int icalcomponent_count_components(icalcomponent *component,
                                                        icalcomponent_kind kind);
 
 /**
-   This takes 2 VCALENDAR components and merges the second one into the first,
-   resolving any problems with conflicting TZIDs. comp_to_merge will no
-   longer exist after calling this function. */
+ *  This takes 2 VCALENDAR components and merges the second one into the first,
+ *  resolving any problems with conflicting TZIDs. comp_to_merge will no
+ *  longer exist after calling this function.
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_merge_component(icalcomponent *comp,
                                                        icalcomponent *comp_to_merge);
 
@@ -149,7 +162,11 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_deref(icalcompiter * i);
 /* Working with embedded error properties */
 LIBICAL_ICAL_EXPORT int icalcomponent_check_restrictions(icalcomponent *comp);
 
-/** @brief Counts embedded errors. */
+/** @brief Returns the number of errors encountered parsing the data.
+ *
+ * This function counts the number times the X-LIC-ERROR occurs
+ * in the data structure.
+ */
 LIBICAL_ICAL_EXPORT int icalcomponent_count_errors(icalcomponent *component);
 
 /** @brief Removes all X-LIC-ERROR properties*/
@@ -178,17 +195,47 @@ If the code was in an OO language, the remaining routines would be
 members of classes derived from icalcomponent. Don't call them on the
 wrong component subtypes. */
 
-/** @brief For VCOMPONENT: Return a reference to the first VEVENT, VTODO or
-   VJOURNAL */
+/** @brief Returns a reference to the first VEVENT, VTODO or
+ * VJOURNAL in the component.
+ */
 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_first_real_component(icalcomponent *c);
 
-/** @brief For VEVENT, VTODO, VJOURNAL and VTIMEZONE: report the start and end
-   times of an event in UTC */
+/**     @brief Gets the timespan covered by this component, in UTC.
+ *
+ *      See icalcomponent_foreach_recurrence() for a better way to
+ *      extract spans from an component.
+ *
+ *      This method can be called on either a VCALENDAR or any real
+ *      component. If the VCALENDAR contains no real component, but
+ *      contains a VTIMEZONE, we return that span instead.
+ *      This might not be a desirable behavior; we keep it for now
+ *      for backward compatibility, but it might be deprecated at a
+ *      future time.
+ *
+ *      FIXME this API needs to be clarified. DTEND is defined as the
+ *      first available time after the end of this event, so the span
+ *      should actually end 1 second before DTEND.
+ */
 LIBICAL_ICAL_EXPORT struct icaltime_span icalcomponent_get_span(icalcomponent *comp);
 
 /******************** Convenience routines **********************/
 
+/**     @brief Sets DTSTART property to the given icaltime,
+ *
+ *      This method respects the icaltime type (DATE vs DATE-TIME) and
+ *      timezone (or lack thereof).
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v);
+
+/**     @brief Gets DTSTART property as an icaltime
+ *
+ *      If DTSTART is a DATE-TIME with a timezone 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.
+ *
+ *      FIXME this is useless until we can flag the failure
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp);
 
 /* For the icalcomponent routines only, dtend and duration are tied
@@ -200,21 +247,104 @@ LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstart(icalcomponent
    be set to ICAL_MALFORMEDDATA_ERROR. If you call a set routine and
    neither exists, the routine will create the appropriate property. */
 
+/**     @brief Gets DTEND property as an icaltime.
+ *
+ *      If a DTEND property is not present but a DURATION is, we use
+ *      that to determine the proper end.
+ *
+ *      If DTSTART is a DATE-TIME with a timezone 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.
+ *
+ *      For the icalcomponent routines only, dtend and duration are tied
+ *      together. If you call the get routine for one and the other
+ *      exists, the routine will calculate the return value. That is, if
+ *      there is a DTEND and you call get_duration, the routine will
+ *      return the difference between DTEND and DTSTART.
+ *
+ *      FIXME this is useless until we can flag the failure
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp);
 
+/**     @brief Sets DTEND property to given icaltime.
+ *
+ *      This method respects the icaltime type (DATE vs DATE-TIME) and
+ *      timezone (or lack thereof).
+ *
+ *      This also checks that a DURATION property isn't already there,
+ *      and returns an error if it is. It's the caller's responsibility
+ *      to remove it.
+ *
+ *      For the icalcomponent routines only, DTEND and DURATION are tied
+ *      together. If you call this routine and DURATION exists, no action
+ *      will be taken and icalerrno will be set to ICAL_MALFORMEDDATA_ERROR.
+ *      If neither exists, the routine will create the appropriate
+ *      property.
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v);
 
+/** @brief Returns the time a VTODO task is DUE.
+ *
+ *  @param comp Valid calendar component.
+ *
+ *  Uses the DUE: property if it exists, otherwise we calculate the DUE
+ *  value by adding the task's duration to the DTSTART time.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_due(icalcomponent *comp);
 
+/** @brief Sets the due date of a VTODO task.
+ *
+ *  @param comp Valid VTODO component.
+ *  @param v    Valid due date time.
+ *
+ *  The DUE and DURATION properties are tied together:
+ *  - If no duration or due properties then sets the DUE property.
+ *  - If a DUE property is already set, then resets it to the value v.
+ *  - If a DURATION property is already set, then calculates the new
+ *    duration based on the supplied value of @p v.
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v);
 
+/**     @brief Sets DURATION property to given icalduration.
+ *
+ *      This method respects the icaltime type (DATE vs DATE-TIME) and
+ *      timezone (or lack thereof).
+ *
+ *      This also checks that a DTEND property isn't already there,
+ *      and returns an error if it is. It's the caller's responsibility
+ *      to remove it.
+ *
+ *      For the icalcomponent routines only, DTEND and DURATION are tied
+ *      together. If you call this routine and DTEND exists, no action
+ *      will be taken and icalerrno will be set to ICAL_MALFORMEDDATA_ERROR.
+ *      If neither exists, the routine will create the appropriate
+ *      property.
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_set_duration(icalcomponent *comp,
                                                     struct icaldurationtype v);
 
+/**     @brief Gets DURATION property as an icalduration
+ *
+ *      For the icalcomponent routines only, DTEND and DURATION are tied
+ *      together.
+ *      If a DURATION property is not present but a DTEND is, we use
+ *      that to determine the proper end.
+ *
+ *      For the icalcomponent routines only, dtend and duration are tied
+ *      together. If you call the get routine for one and the other
+ *      exists, the routine will calculate the return value. That is, if
+ *      there is a DTEND and you call get_duration, the routine will
+ *      return the difference between DTEND and DTSTART.
+ */
 LIBICAL_ICAL_EXPORT struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp);
 
+/** @brief Sets the METHOD property to the given method.
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method);
 
+/** @brief Returns the METHOD property.
+ */
 LIBICAL_ICAL_EXPORT icalproperty_method icalcomponent_get_method(icalcomponent *comp);
 
 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstamp(icalcomponent *comp);
@@ -259,21 +389,63 @@ LIBICAL_ICAL_EXPORT void icalcomponent_set_status(icalcomponent *comp, enum ical
 LIBICAL_ICAL_EXPORT enum icalproperty_status icalcomponent_get_status(icalcomponent *comp);
 
 /** @brief Calls the given function for each TZID parameter found in the
-    component, and any subcomponents. */
+ *  component, and any subcomponents.
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_foreach_tzid(icalcomponent *comp,
                                                     void (*callback) (icalparameter *param,
                                                                       void *data),
                                                     void *callback_data);
 
 /** @brief Returns the icaltimezone in the component corresponding to the
-    TZID, or NULL if it can't be found. */
+ *  TZID, or NULL if it can't be found.
+ */
 LIBICAL_ICAL_EXPORT icaltimezone *icalcomponent_get_timezone(icalcomponent *comp,
                                                              const char *tzid);
 
+/**
+ * @brief Decides if a recurrence is acceptable.
+ *
+ * @param comp       A valid icalcomponent.
+ * @param dtstart    The base dtstart value for this component.
+ * @param recurtime  The time to test against.
+ *
+ * @return true if the recurrence value is excluded, false otherwise.
+ *
+ * This function decides if a specific recurrence value is
+ * excluded by EXRULE or EXDATE properties.
+ *
+ * It's not the most efficient code.  You might get better performance
+ * if you assume that recurtime is always increasing for each
+ * call. Then you could:
+ *
+ *   - sort the EXDATE values
+ *   - save the state of each EXRULE iterator for the next call.
+ *
+ * In this case though you don't need to worry how you call this
+ * function.  It will always return the correct result.
+ */
 LIBICAL_ICAL_EXPORT int icalproperty_recurrence_is_excluded(icalcomponent *comp,
                                                             struct icaltimetype *dtstart,
                                                             struct icaltimetype *recurtime);
 
+/**
+ * @brief Cycles through all recurrences of an event.
+ *
+ * @param comp           A valid VEVENT component
+ * @param start          Ignore timespans before this
+ * @param end            Ignore timespans after this
+ * @param callback       Function called for each timespan within the range
+ * @param callback_data  Pointer passed back to the callback function
+ *
+ * This function will call the specified callback function for once
+ * for the base value of DTSTART, and foreach recurring date/time
+ * value.
+ *
+ * It will filter out events that are specified as an EXDATE or an EXRULE.
+ *
+ * @todo We do not filter out duplicate RRULES/RDATES
+ * @todo We do not handle RDATEs with explicit periods
+ */
 LIBICAL_ICAL_EXPORT void icalcomponent_foreach_recurrence(icalcomponent *comp,
                                                           struct icaltimetype start,
                                                           struct icaltimetype end,
diff --git a/src/libical/icalenums.c b/src/libical/icalenums.c
index 4f25c920..4e184795 100644
--- a/src/libical/icalenums.c
+++ b/src/libical/icalenums.c
@@ -77,8 +77,6 @@ static const struct
     {ICAL_UNKNOWN_STATUS, 0, 0, "Error: Unknown request status"}
 };
 
-/*** @brief Returns the descriptive text for a request status
- */
 const char *icalenum_reqstat_desc(icalrequeststatus stat)
 {
     int i;
@@ -101,8 +99,6 @@ char *icalenum_reqstat_code(icalrequeststatus stat)
     return buf;
 }
 
-/*** @brief Returns the code for a request status
- */
 char *icalenum_reqstat_code_r(icalrequeststatus stat)
 {
     int i, major, minor;
@@ -119,8 +115,6 @@ char *icalenum_reqstat_code_r(icalrequeststatus stat)
     return NULL;
 }
 
-/*** @brief Returns the major number for a request status
- */
 short icalenum_reqstat_major(icalrequeststatus stat)
 {
     int i;
@@ -133,8 +127,6 @@ short icalenum_reqstat_major(icalrequeststatus stat)
     return -1;
 }
 
-/*** @brief Returns the minor number for a request status
- */
 short icalenum_reqstat_minor(icalrequeststatus stat)
 {
     int i;
@@ -147,8 +139,6 @@ short icalenum_reqstat_minor(icalrequeststatus stat)
     return -1;
 }
 
-/*** @brief Returns a request status for major/minor status numbers
- */
 icalrequeststatus icalenum_num_to_reqstat(short major, short minor)
 {
     int i;
diff --git a/src/libical/icalenums.h b/src/libical/icalenums.h
index a00def48..6d3ac09e 100644
--- a/src/libical/icalenums.h
+++ b/src/libical/icalenums.h
@@ -114,16 +114,26 @@ typedef enum icalrequeststatus
     ICAL_9_0_UNRECOGNIZED_COMMAND
 } icalrequeststatus;
 
+/** @brief Returns the descriptive text for a request status.
+ */
 LIBICAL_ICAL_EXPORT const char *icalenum_reqstat_desc(icalrequeststatus stat);
 
+/** @brief Returns the major number for a request status
+ */
 LIBICAL_ICAL_EXPORT short icalenum_reqstat_major(icalrequeststatus stat);
 
+/** @brief Returns the minor number for a request status
+ */
 LIBICAL_ICAL_EXPORT short icalenum_reqstat_minor(icalrequeststatus stat);
 
+/** @brief Returns a request status for major/minor status numbers
+ */
 LIBICAL_ICAL_EXPORT icalrequeststatus icalenum_num_to_reqstat(short major, short minor);
 
 LIBICAL_ICAL_EXPORT char *icalenum_reqstat_code(icalrequeststatus stat);
 
+/** @brief Returns the code for a request status.
+ */
 LIBICAL_ICAL_EXPORT char *icalenum_reqstat_code_r(icalrequeststatus stat);
 
 /***********************************************************************
diff --git a/src/libical/icalparameter.c b/src/libical/icalparameter.c
index a699f0ca..f27dc8c7 100644
--- a/src/libical/icalparameter.c
+++ b/src/libical/icalparameter.c
@@ -256,16 +256,14 @@ static void icalparameter_append_encoded_value(char **buf, char **buf_ptr,
     }
 }
 
-/**
- * Returns a string representation of the parameter according to RFC5445/RFC6868.
- *
- * param        = param-name "=" param-value
- * param-name   = iana-token / x-token
- * param-value  = paramtext /quoted-string
- * paramtext    = *SAFE-CHAR
- * quoted-string= DQUOTE *QSAFE-CHAR DQUOTE
- * QSAFE-CHAR   = any character except CTLs and DQUOTE
- * SAFE-CHAR    = any character except CTLs, DQUOTE. ";", ":", ","
+/*
+ * - param        = param-name "=" param-value
+ * - param-name   = iana-token / x-token
+ * - param-value  = paramtext /quoted-string
+ * - paramtext    = *SAFE-CHAR
+ * - quoted-string= DQUOTE *QSAFE-CHAR DQUOTE
+ * - QSAFE-CHAR   = any character except CTLs and DQUOTE
+ * - SAFE-CHAR    = any character except CTLs, DQUOTE. ";", ":", ","
  */
 char *icalparameter_as_ical_string_r(icalparameter *param)
 {
@@ -423,7 +421,6 @@ icalproperty *icalparameter_get_parent(icalparameter *param)
     return param->parent;
 }
 
-/* Returns 1 if parameters have same name in ICAL, otherwise 0 */
 int icalparameter_has_same_name(icalparameter *param1, icalparameter *param2)
 {
     icalparameter_kind kind1;
diff --git a/src/libical/icalparameter.h b/src/libical/icalparameter.h
index 84691116..8a7bc946 100644
--- a/src/libical/icalparameter.h
+++ b/src/libical/icalparameter.h
@@ -208,9 +208,9 @@ LIBICAL_ICAL_EXPORT void icalparameter_free(icalparameter *parameter);
 LIBICAL_ICAL_EXPORT char *icalparameter_as_ical_string(icalparameter *parameter);
 
 /**
- * @brief Converts ::icalparameter into an string representation
+ * @brief Converts ::icalparameter into an string representation according to RFC5445/RFC6868.
  * @param parameter The ::icalparameter to convert
- * @return A string representing the parameter according to RFC5445/RFC6868.
+ * @return A string representing the parameter
  * @sa icalparameter_as_ical_string()
  *
  * @par Error handling
diff --git a/src/libical/icalparser.c b/src/libical/icalparser.c
index 3b6fa74b..3bc3d5f6 100644
--- a/src/libical/icalparser.c
+++ b/src/libical/icalparser.c
@@ -213,7 +213,7 @@ static char *parser_get_prop_name(char *line, char **end)
     return str;
 }
 
-/* Decode parameter value per RFC6868 */
+/** Decode parameter value per RFC6868 */
 static void parser_decode_param_value(char *value)
 {
     char *in, *out;
@@ -473,10 +473,6 @@ static char *parser_get_next_parameter(char *line, char **end)
     }
 }
 
-/**
- * Get a single property line, from the property name through the
- * final new line, and include any continuation lines
- */
 char *icalparser_get_line(icalparser *parser,
                           icalparser_line_gen_func line_gen_func)
 {
diff --git a/src/libical/icalparser.h b/src/libical/icalparser.h
index 9d8bd91a..765f7730 100644
--- a/src/libical/icalparser.h
+++ b/src/libical/icalparser.h
@@ -326,6 +326,7 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalparser_parse_string(const char *str);
  *
  * This function uses the supplied @a line_gen_func to read data in,
  * until it has read a full line, and returns the full line.
+ * It includes any continuation lines, which start with a space after a newline.
  * To supply arbitrary data (as the parameter @a d) to your @a line_gen_func,
  * call icalparser_set_gen_data().
  */
diff --git a/src/libical/icalproperty.c b/src/libical/icalproperty.c
index fb365444..a62dcdf3 100644
--- a/src/libical/icalproperty.c
+++ b/src/libical/icalproperty.c
@@ -625,16 +625,6 @@ char *icalproperty_get_parameter_as_string_r(icalproperty *prop, const char *nam
     return str;
 }
 
-/** @brief Removes all parameters with the specified kind.
- *
- *  @param prop   A valid icalproperty.
- *  @param kind   The kind to remove (ex. ICAL_TZID_PARAMETER)
- *
- *  See icalproperty_remove_parameter_by_name() and
- *  icalproperty_remove_parameter_by_ref() for alternate ways of
- *  removing parameters
- */
-
 void icalproperty_remove_parameter_by_kind(icalproperty *prop, icalparameter_kind kind)
 {
     pvl_elem p;
@@ -652,20 +642,6 @@ void icalproperty_remove_parameter_by_kind(icalproperty *prop, icalparameter_kin
     }
 }
 
-/** @brief Removes all parameters with the specified name.
- *
- *  @param prop   A valid icalproperty.
- *  @param name   The name of the parameter to remove
- *
- *  This function removes parameters with the given name.  The name
- *  corresponds to either a built-in name (TZID, etc.) or the name of
- *  an extended parameter (X-FOO)
- *
- *  See icalproperty_remove_parameter_by_kind() and
- *  icalproperty_remove_parameter_by_ref() for alternate ways of removing
- *  parameters
- */
-
 void icalproperty_remove_parameter_by_name(icalproperty *prop, const char *name)
 {
     pvl_elem p;
@@ -695,15 +671,6 @@ void icalproperty_remove_parameter_by_name(icalproperty *prop, const char *name)
     }
 }
 
-/** @brief Removes the specified parameter reference from the property.
- *
- *  @param prop   A valid icalproperty.
- *  @param parameter   A reference to a specific icalparameter.
- *
- *  This function removes the specified parameter reference from the
- *  property.
- */
-
 void icalproperty_remove_parameter_by_ref(icalproperty *prop, icalparameter *parameter)
 {
     pvl_elem p;
diff --git a/src/libical/icalproperty.h b/src/libical/icalproperty.h
index f30021e2..f4411cf6 100644
--- a/src/libical/icalproperty.h
+++ b/src/libical/icalproperty.h
@@ -59,12 +59,42 @@ LIBICAL_ICAL_EXPORT const char *icalproperty_get_parameter_as_string(icalpropert
 LIBICAL_ICAL_EXPORT char *icalproperty_get_parameter_as_string_r(icalproperty *prop,
                                                                  const char *name);
 
+/** @brief Removes all parameters with the specified kind.
+ *
+ *  @param prop   A valid icalproperty.
+ *  @param kind   The kind to remove (ex. ICAL_TZID_PARAMETER)
+ *
+ *  See icalproperty_remove_parameter_by_name() and
+ *  icalproperty_remove_parameter_by_ref() for alternate ways of
+ *  removing parameters
+ */
 LIBICAL_ICAL_EXPORT void icalproperty_remove_parameter_by_kind(icalproperty *prop,
                                                                icalparameter_kind kind);
 
+/** @brief Removes all parameters with the specified name.
+ *
+ *  @param prop   A valid icalproperty.
+ *  @param name   The name of the parameter to remove
+ *
+ *  This function removes parameters with the given name.  The name
+ *  corresponds to either a built-in name (TZID, etc.) or the name of
+ *  an extended parameter (X-FOO)
+ *
+ *  See icalproperty_remove_parameter_by_kind() and
+ *  icalproperty_remove_parameter_by_ref() for alternate ways of removing
+ *  parameters
+ */
 LIBICAL_ICAL_EXPORT void icalproperty_remove_parameter_by_name(icalproperty *prop,
                                                                const char *name);
 
+/** @brief Removes the specified parameter reference from the property.
+ *
+ *  @param prop   A valid icalproperty.
+ *  @param parameter   A reference to a specific icalparameter.
+ *
+ *  This function removes the specified parameter reference from the
+ *  property.
+ */
 LIBICAL_ICAL_EXPORT void icalproperty_remove_parameter_by_ref(icalproperty *prop,
                                                               icalparameter *param);
 
diff --git a/src/libical/icalrecur.c b/src/libical/icalrecur.c
index b3e67a6e..f01c66cd 100644
--- a/src/libical/icalrecur.c
+++ b/src/libical/icalrecur.c
@@ -985,7 +985,7 @@ static void setup_defaults(icalrecur_iterator *impl,
     }
 }
 
-/* Calculate the number of Gregorian months between 2 dates */
+/** Calculate the number of Gregorian months between 2 dates */
 static int __greg_month_diff(icaltimetype a, icaltimetype b)
 {
     return (12 * (b.year - a.year) + (b.month - a.month));
@@ -1464,7 +1464,7 @@ static int initialize_rscale(icalrecur_iterator *impl)
     return 1;
 }
 
-/* Sets Gregorian date and convert to RSCALE */
+/** Sets Gregorian date and convert to RSCALE */
 static void set_datetime(icalrecur_iterator *impl, icaltimetype date)
 {
     UErrorCode status = U_ZERO_ERROR;
@@ -1497,7 +1497,7 @@ static void set_datetime(icalrecur_iterator *impl, icaltimetype date)
     }
 }
 
-/* Calculate the number of RSCALE months between 2 dates */
+/** Calculate the number of RSCALE months between 2 dates */
 static int month_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
 {
     int diff;
@@ -1528,7 +1528,7 @@ static int month_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
     return diff;
 }
 
-/* Calculate the number of RSCALE days between 2 dates */
+/** Calculate the number of RSCALE days between 2 dates */
 static int day_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
 {
     UErrorCode status = U_ZERO_ERROR;
@@ -1613,7 +1613,7 @@ static int get_day_of_week(icalrecur_iterator *impl)
     return icaltime_day_of_week(impl->last);
 }
 
-/* Calculate ISO weeks per year
+/** Calculate ISO weeks per year
    https://en.wikipedia.org/wiki/ISO_week_date#Weeks_per_year */
 static int weeks_in_year(int year)
 {
@@ -1624,7 +1624,7 @@ static int weeks_in_year(int year)
     return (52 + is_long);
 }
 
-/* Calculate ISO week number
+/** Calculate ISO week number
    https://en.wikipedia.org/wiki/ISO_week_date#Calculation */
 static int get_week_number(icalrecur_iterator *impl, struct icaltimetype tt)
 {
@@ -1759,7 +1759,7 @@ static int initialize_rscale(icalrecur_iterator *impl)
     return 1;
 }
 
-/* Sets Gregorian date */
+/** Sets Gregorian date */
 static void set_datetime(icalrecur_iterator *impl, icaltimetype date)
 {
     impl->last.year = date.year;
@@ -1778,7 +1778,7 @@ static void set_datetime(icalrecur_iterator *impl, icaltimetype date)
     }
 }
 
-/* Calculate the number of Gregorian months between 2 dates */
+/** Calculate the number of Gregorian months between 2 dates */
 static int month_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
 {
     _unused(impl);
@@ -1786,7 +1786,7 @@ static int month_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
     return __greg_month_diff(a, b);
 }
 
-/* Calculate the number of Gregorian days between 2 dates */
+/** Calculate the number of Gregorian days between 2 dates */
 static int day_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
 {
     return __day_diff(impl, a, b);
@@ -1957,7 +1957,7 @@ void icalrecur_iterator_free(icalrecur_iterator *i)
     free(i);
 }
 
-/* Calculate the number of days between 2 dates */
+/** Calculate the number of days between 2 dates */
 static int __day_diff(icalrecur_iterator *impl, icaltimetype a, icaltimetype b)
 {
     int diff;
@@ -2220,7 +2220,7 @@ static int check_set_position(icalrecur_iterator *impl, int set_pos)
     return found;
 }
 
-/* Add each BYMONTHDAY to the year days bitmask */
+/** Add each BYMONTHDAY to the year days bitmask */
 static int expand_bymonth_days(icalrecur_iterator *impl, int year, int month)
 {
     int i, set_pos_total = 0;
@@ -2276,7 +2276,7 @@ static int expand_bymonth_days(icalrecur_iterator *impl, int year, int month)
     return set_pos_total;
 }
 
-/* Expand the BYDAY rule part and apply it to the year days map. */
+/** Expand the BYDAY rule part and apply it to the year days map. */
 static int expand_by_day(icalrecur_iterator *impl, int year,
                          int doy_offset, int last_day,
                          int first_dow, int last_dow,
@@ -2372,7 +2372,7 @@ static int expand_by_day(icalrecur_iterator *impl, int year,
     return set_pos_total;
 }
 
-/* "Filter" the year days bitmask with each BYSETPOS */
+/** "Filter" the year days bitmask with each BYSETPOS */
 static void filter_bysetpos(icalrecur_iterator *impl, int pos_total,
                             int start_doy, int end_doy)
 {
@@ -2396,7 +2396,7 @@ static void filter_bysetpos(icalrecur_iterator *impl, int pos_total,
     }
 }
 
-/* For INTERVAL=MONTHLY, set up the year days bitmask in the iterator to
+/** For INTERVAL=MONTHLY, set up the year days bitmask in the iterator to
    list all of the days of the current month that are specified in this
    rule. */
 static int expand_month_days(icalrecur_iterator *impl, int year, int month)
@@ -2522,7 +2522,7 @@ static int next_week(icalrecur_iterator *impl)
     return end_of_data;
 }
 
-/* For INTERVAL=YEARLY, set up the year days bitmask in the iterator to
+/** For INTERVAL=YEARLY, set up the year days bitmask in the iterator to
    list all of the days of the current year that are specified in this
    rule. */
 static int expand_year_days(icalrecur_iterator *impl, int year)
@@ -3042,17 +3042,6 @@ void icalrecurrencetype_clear(struct icalrecurrencetype *recur)
     recur->skip = ICAL_SKIP_OMIT;
 }
 
-/** The 'day' element of icalrecurrencetype_weekday is encoded to
- * allow representation of both the day of the week ( Monday, Tuesday),
- * but also the Nth day of the week ( First tuesday of the month, last
- * thursday of the year) These routines decode the day values.
- *
- * The day's position in the period ( Nth-ness) and the numerical
- * value of the day are encoded together as: pos*7 + dow
- *
- * A position of 0 means 'any' or 'every'
- */
-
 enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week(short day)
 {
     return abs(day) % 8;
@@ -3069,12 +3058,12 @@ int icalrecurrencetype_day_position(short day)
     return pos;
 }
 
-/**
+/*
  * The 'month' element of the by_month array is encoded to allow
  * representation of the "L" leap suffix (RFC 7529).
  * These routines decode the month values.
  *
- * The "L" suffix is encoded by setting a high-order bit
+ * The "L" suffix is encoded by setting a high-order bit.
  */
 
 int icalrecurrencetype_month_is_leap(short month)
@@ -3087,12 +3076,6 @@ int icalrecurrencetype_month_month(short month)
     return (month & ~LEAP_MONTH);
 }
 
-/** Fill an array with the 'count' number of occurrences generated by
- * the rrule. Note that the times are returned in UTC, but the times
- * are calculated in local time. YOu will have to convert the results
- * back into local time before using them.
- */
-
 int icalrecur_expand_recurrence(const char *rule,
                                 time_t start, int count, time_t *array)
 {
diff --git a/src/libical/icalrecur.h b/src/libical/icalrecur.h
index 5ed3ab2e..c2438bc7 100644
--- a/src/libical/icalrecur.h
+++ b/src/libical/icalrecur.h
@@ -172,11 +172,27 @@ struct icalrecurrencetype
     short by_second[ICAL_BY_SECOND_SIZE];
     short by_minute[ICAL_BY_MINUTE_SIZE];
     short by_hour[ICAL_BY_HOUR_SIZE];
-    short by_day[ICAL_BY_DAY_SIZE];     /* Encoded value, see below */
+    short by_day[ICAL_BY_DAY_SIZE];             /**< @brief Encoded value
+        *
+        * The 'day' element of the by_day array is encoded to allow
+        * representation of both the day of the week ( Monday, Tueday), but
+        * also the Nth day of the week (first Tuesday of the month, last
+        * Thursday of the year).
+        *
+        * These values are decoded by icalrecurrencetype_day_day_of_week() and
+        * icalrecurrencetype_day_position().
+        */
     short by_month_day[ICAL_BY_MONTHDAY_SIZE];
     short by_year_day[ICAL_BY_YEARDAY_SIZE];
     short by_week_no[ICAL_BY_WEEKNO_SIZE];
-    short by_month[ICAL_BY_MONTH_SIZE];
+    short by_month[ICAL_BY_MONTH_SIZE];         /**< @brief Encoded value
+        *
+        * The 'month' element of the by_month array is encoded to allow
+        * representation of the "L" leap suffix (RFC 7529).
+        *
+        * These values are decoded by icalrecurrencetype_month_is_leap()
+        * and icalrecurrencetype_month_month().
+        */
     short by_set_pos[ICAL_BY_SETPOS_SIZE];
 
     /* For RSCALE extension (RFC 7529) */
@@ -190,32 +206,44 @@ LIBICAL_ICAL_EXPORT icalarray *icalrecurrencetype_rscale_supported_calendars(voi
 
 LIBICAL_ICAL_EXPORT void icalrecurrencetype_clear(struct icalrecurrencetype *r);
 
-/**
- * Array Encoding
- *
- * The 'day' element of the by_day array is encoded to allow
- * representation of both the day of the week ( Monday, Tueday), but also
- * the Nth day of the week ( First tuesday of the month, last thursday of
- * the year) These routines decode the day values
+/*
+ * Routines to decode the day values of the by_day array
  */
 
-/** 1 == Monday, etc. */
+/** @brief Decodes a day to a weekday.
+ *
+ * @returns The decoded day of the week. 1 is Monday, 2 is Tuesday, etc.
+ * A position of 0 means 'any' or 'every'.
+ *
+ * The 'day' element of icalrecurrencetype_weekday is encoded to
+ * allow representation of both the day of the week ( Monday, Tuesday),
+ * but also the Nth day of the week ( First tuesday of the month, last
+ * thursday of the year) These routines decode the day values.
+ *
+ * The day's position in the period ( Nth-ness) and the numerical
+ * value of the day are encoded together as: pos*7 + dow.
+ */
 LIBICAL_ICAL_EXPORT enum icalrecurrencetype_weekday icalrecurrencetype_day_day_of_week(short day);
 
-/** 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc. */
+/** @brief Decodes a day to a position of the weekday.
+ *
+ * @returns The position of the day in the week.
+ * 0 == any of day of week. 1 == first, 2 = second, -2 == second to last, etc.
+ * 0 means 'any' or 'every'.
+ */
 LIBICAL_ICAL_EXPORT int icalrecurrencetype_day_position(short day);
 
-/**
- * The 'month' element of the by_month array is encoded to allow
- * representation of the "L" leap suffix (RFC 7529).
- * These routines decode the month values.
+/*
+ * Routines to decode the 'month' element of the by_month array
  */
 
 LIBICAL_ICAL_EXPORT int icalrecurrencetype_month_is_leap(short month);
 
 LIBICAL_ICAL_EXPORT int icalrecurrencetype_month_month(short month);
 
-/** Recurrence rule parser */
+/*
+ * Recurrence rule parser
+ */
 
 /** Convert between strings and recurrencetype structures. */
 LIBICAL_ICAL_EXPORT struct icalrecurrencetype icalrecurrencetype_from_string(const char *str);
@@ -224,7 +252,9 @@ LIBICAL_ICAL_EXPORT char *icalrecurrencetype_as_string(struct icalrecurrencetype
 
 LIBICAL_ICAL_EXPORT char *icalrecurrencetype_as_string_r(struct icalrecurrencetype *recur);
 
-/** Recurrence iteration routines */
+/*
+ * Recurrence iteration routines
+ */
 
 typedef struct icalrecur_iterator_impl icalrecur_iterator;
 
@@ -248,9 +278,15 @@ LIBICAL_ICAL_EXPORT struct icaltimetype icalrecur_iterator_next(icalrecur_iterat
 /** Frees the iterator. */
 LIBICAL_ICAL_EXPORT void icalrecur_iterator_free(icalrecur_iterator *);
 
-/**
- * Fills array up with at most 'count' time_t values, each
- *  representing an occurrence time in seconds past the POSIX epoch.
+/** @brief Fills an array with the 'count' number of occurrences generated by
+ * the rrule.
+ *
+ * Specifically, this fills @p array up with at most 'count' time_t values, each
+ * representing an occurrence time in seconds past the POSIX epoch.
+ *
+ * Note that the times are returned in UTC, but the times
+ * are calculated in local time. You will have to convert the results
+ * back into local time before using them.
  */
 LIBICAL_ICAL_EXPORT int icalrecur_expand_recurrence(const char *rule, time_t start,
                                                     int count, time_t *array);
diff --git a/src/libical/icaltime.c b/src/libical/icaltime.c
index 689e4da6..aaea998c 100644
--- a/src/libical/icaltime.c
+++ b/src/libical/icaltime.c
@@ -180,30 +180,6 @@ static time_t make_time(struct tm *tm, int tzm)
     return (tim);
 }
 
-/**     @brief Constructor.
- *
- *      @param tm The time
- *      @param is_date Boolean: 1 means we should treat tm as a DATE
- *      @param zone The timezone tm is in, NULL means to treat tm as a
- *              floating time
- *
- *      Returns a new icaltime instance, initialized to the given time
- *      expressed as seconds past UNIX epoch, optionally using the given
- *      timezone.
- *
- *      If the caller specifies the is_date param as TRUE, the returned
- *      object is of DATE type, otherwise the input is meant to be of
- *      DATE-TIME type.
- *      If the zone is not specified (NULL zone param) the time is taken
- *      to be floating, that is, valid in any timezone. Note that, in
- *      addition to the uses specified in [RFC5545], this can be used
- *      when doing simple math on couples of times.
- *      If the zone is specified (UTC or otherwise), it's stored in the
- *      object and it's used as the native timezone for this object.
- *      This means that the caller can convert this time to a different
- *      target timezone with no need to store the source timezone.
- *
- */
 struct icaltimetype icaltime_from_timet_with_zone(const time_t tm, const int is_date,
                                                   const icaltimezone *zone)
 {
@@ -242,19 +218,11 @@ struct icaltimetype icaltime_from_timet_with_zone(const time_t tm, const int is_
     return tt;
 }
 
-/**     @brief Convenience constructor.
- *
- * @returns The current time in the given timezone, as an icaltimetype.
- */
 struct icaltimetype icaltime_current_time_with_zone(const icaltimezone *zone)
 {
     return icaltime_from_timet_with_zone(time(NULL), 0, zone);
 }
 
-/**     @brief Convenience constructor.
- *
- * @returns The current day as an icaltimetype, with is_date set.
- */
 struct icaltimetype icaltime_today(void)
 {
     return icaltime_from_timet_with_zone(time(NULL), 1, NULL);
@@ -291,14 +259,6 @@ time_t icaltime_as_timet(const struct icaltimetype tt)
     return t;
 }
 
-/**     @brief Returns the time as seconds past the UNIX epoch, using the
- *      given timezone.
- *
- *      This convenience method combines a call to icaltime_convert_to_zone()
- *      with a call to icaltime_as_timet().
- *      If the input timezone is null, no conversion is done; that is, the
- *      time is simply returned as time_t in its native timezone.
- */
 time_t icaltime_as_timet_with_zone(const struct icaltimetype tt, const icaltimezone *zone)
 {
     icaltimezone *utc_zone;
@@ -337,11 +297,6 @@ time_t icaltime_as_timet_with_zone(const struct icaltimetype tt, const icaltimez
     return t;
 }
 
-/**
- * @brief Returns a string represention of the time, in RFC5545 format.
- *
- * The string is owned by libical.
- */
 const char *icaltime_as_ical_string(const struct icaltimetype tt)
 {
     char *buf;
@@ -351,11 +306,6 @@ const char *icaltime_as_ical_string(const struct icaltimetype tt)
     return buf;
 }
 
-/**
- * @brief Returns a string represention of the time, in RFC5545 format.
- *
- * The string is owned by the caller.
- */
 char *icaltime_as_ical_string_r(const struct icaltimetype tt)
 {
     size_t size = 17;
@@ -377,16 +327,7 @@ char *icaltime_as_ical_string_r(const struct icaltimetype tt)
     return buf;
 }
 
-/**
- *      @brief Resets all of the time components to be in their normal ranges.
- *
- *      For instance, given a time with minutes=70, the minutes will be
- *      reduces to 10, and the hour incremented. This allows the caller
- *      to do arithmetic on times without worrying about overflow or
- *      underflow.
- *
- *      Implementation note: we call icaltime_adjust() with no adjustment.
- */
+/* Implementation note: we call icaltime_adjust() with no adjustment. */
 struct icaltimetype icaltime_normalize(const struct icaltimetype tt)
 {
     struct icaltimetype ret = tt;
@@ -395,15 +336,6 @@ struct icaltimetype icaltime_normalize(const struct icaltimetype tt)
     return ret;
 }
 
-/**     @brief Contructor.
- *
- * Creates a time from an ISO format string.
- *
- * @todo If the given string specifies a DATE-TIME not in UTC, there
- *       is no way to know if this is a floating time or really refers to a
- *       timezone. We should probably add a new constructor:
- *       icaltime_from_string_with_zone()
- */
 struct icaltimetype icaltime_from_string(const char *str)
 {
     struct icaltimetype tt = icaltime_null_time();
@@ -480,11 +412,6 @@ struct icaltimetype icaltime_from_string(const char *str)
     return icaltime_null_time();
 }
 
-/**
- * @brief Returns whether the specified year is a leap year.
- *
- * Year is the normal year, e.g. 2001.
- */
 int icaltime_is_leap_year(const int year)
 {
     if (year <= 1752) {
@@ -547,9 +474,6 @@ int icaltime_day_of_week(const struct icaltimetype t)
     return jt.weekday + 1;
 }
 
-/** @brief Returns the day of the year that the first day of the week (Sunday)
- * is on.
- */
 int icaltime_start_doy_week(const struct icaltimetype t, int fdow)
 {
     UTinstant jt;
@@ -574,10 +498,6 @@ int icaltime_start_doy_week(const struct icaltimetype t, int fdow)
     return jt.day_of_year - delta;
 }
 
-/**
- * @todo Doesn't take into account the start day of the
- * week. strftime assumes that weeks start on Monday.
- */
 int icaltime_week_number(const struct icaltimetype ictt)
 {
     UTinstant jt;
@@ -597,9 +517,6 @@ int icaltime_week_number(const struct icaltimetype ictt)
     return (jt.day_of_year - jt.weekday) / 7;
 }
 
-/**
- *      @brief Returns the day of the year, counting from 1 (Jan 1st).
- */
 int icaltime_day_of_year(const struct icaltimetype t)
 {
     int is_leap = icaltime_is_leap_year(t.year);
@@ -607,12 +524,6 @@ int icaltime_day_of_year(const struct icaltimetype t)
     return days_in_year_passed_month[is_leap][t.month - 1] + t.day;
 }
 
-/**     @brief Contructor.
- *
- *      Creates a new time, given a day of year and a year.
- *
- *      Note that Jan 1 is day #1, not 0.
- */
 struct icaltimetype icaltime_from_day_of_year(const int _doy, const int _year)
 {
     struct icaltimetype tt = icaltime_null_date();
@@ -648,11 +559,6 @@ struct icaltimetype icaltime_from_day_of_year(const int _doy, const int _year)
     return tt;
 }
 
-/**     @brief Constructor.
- *
- *      @returns A null time, which indicates no time has been set.
- *      This time represents the beginning of the epoch.
- */
 struct icaltimetype icaltime_null_time(void)
 {
     struct icaltimetype t;
@@ -662,10 +568,6 @@ struct icaltimetype icaltime_null_time(void)
     return t;
 }
 
-/**     @brief Constructor.
- *
- *      @returns A null date, which indicates no time has been set.
- */
 struct icaltimetype icaltime_null_date(void)
 {
     struct icaltimetype t;
@@ -685,12 +587,6 @@ struct icaltimetype icaltime_null_date(void)
     return t;
 }
 
-/**
- *      @brief Returns false if the time is clearly invalid, but is not null.
- *
- *      This is usually the result of creating a new time type but not
- *      clearing it, or setting one of the flags to an illegal value.
- */
 int icaltime_is_valid_time(const struct icaltimetype t)
 {
     if (t.year < 0 || t.year > 3000 || t.is_date > 1 || t.is_date < 0) {
@@ -700,25 +596,16 @@ int icaltime_is_valid_time(const struct icaltimetype t)
     }
 }
 
-/**     @brief Returns true if time is a DATE.
- */
 int icaltime_is_date(const struct icaltimetype t)
 {
     return t.is_date;
 }
 
-/**     @brief Returns true if time is relative to UTC zone.
- *
- *      @todo  We should only check the zone.
- */
 int icaltime_is_utc(const struct icaltimetype t)
 {
     return t.zone == icaltimezone_get_utc_timezone();
 }
 
-/**
- *      Returns true if the time is null.
- */
 int icaltime_is_null_time(const struct icaltimetype t)
 {
     if (t.second + t.minute + t.hour + t.day + t.month + t.year == 0) {
@@ -728,13 +615,6 @@ int icaltime_is_null_time(const struct icaltimetype t)
     return 0;
 }
 
-/**
- *      @brief Returns -1, 0, or 1 to indicate that a<b, a==b, or a>b.
- *
- *      This calls icaltime_compare function after converting them to the utc
- *      timezone.
- */
-
 int icaltime_compare(const struct icaltimetype a_in, const struct icaltimetype b_in)
 {
     struct icaltimetype a, b;
@@ -790,10 +670,6 @@ int icaltime_compare(const struct icaltimetype a_in, const struct icaltimetype b
     return 0;
 }
 
-/**
- *      @brief Like icaltime_compare, but only use the date parts.
- */
-
 int icaltime_compare_date_only(const struct icaltimetype a_in,
                                const struct icaltimetype b_in)
 {
@@ -824,11 +700,6 @@ int icaltime_compare_date_only(const struct icaltimetype a_in,
     return 0;
 }
 
-/**
- *      @brief Like icaltime_compare, but only use the date parts;
- *      accepts timezone.
- */
-
 int icaltime_compare_date_only_tz(const struct icaltimetype a_in,
                                   const struct icaltimetype b_in,
                                   icaltimezone *tz)
@@ -866,12 +737,6 @@ struct icaldurationtype  icaltime_subtract(struct icaltimetype t1,
                                            struct icaltimetype t2)
 */
 
-/**     @brief Internal, shouldn't be part of the public API
- *
- *      Adds (or subtracts) a time from a icaltimetype.
- *      NOTE: This function is exactly the same as icaltimezone_adjust_change()
- *      except for the type of the first parameter.
- */
 void icaltime_adjust(struct icaltimetype *tt,
                      const int days, const int hours,
                      const int minutes, const int seconds)
@@ -957,16 +822,6 @@ void icaltime_adjust(struct icaltimetype *tt,
     tt->day = day;
 }
 
-/**     @brief Converts time to a given timezone.
- *
- *      Converts a time from its native timezone to a given timezone.
- *
- *      If tt is a date, the returned time is an exact
- *      copy of the input. If it's a floating time, the returned object
- *      represents the same time translated to the given timezone.
- *      Otherwise the time will be converted to the new
- *      time zone, and its native timezone set to the right timezone.
- */
 struct icaltimetype icaltime_convert_to_zone(const struct icaltimetype tt, icaltimezone *zone)
 {
     struct icaltimetype ret = tt;
@@ -1010,12 +865,6 @@ const char *icaltime_get_tzid(const struct icaltimetype t)
     }
 }
 
-/**     @brief Sets the timezone.
- *
- *      Forces the icaltime to be interpreted relative to another timezone.
- *      If you need to do timezone conversion, applying offset adjustments,
- *      then you should use icaltime_convert_to_zone instead.
- */
 struct icaltimetype icaltime_set_timezone(struct icaltimetype *t, const icaltimezone *zone)
 {
     /* If it's a date do nothing */
@@ -1032,16 +881,6 @@ struct icaltimetype icaltime_set_timezone(struct icaltimetype *t, const icaltime
     return *t;
 }
 
-/**
- *  @brief Builds an icaltimespan given a start time, end time and busy value.
- *
- *  @param dtstart   The beginning time of the span, can be a date-time
- *                   or just a date.
- *  @param dtend     The end time of the span.
- *  @param is_busy   A boolean value, 0/1.
- *  @returns          A span using the supplied values. The times are specified in UTC.
- */
-
 icaltime_span icaltime_span_new(struct icaltimetype dtstart, struct icaltimetype dtend, int is_busy)
 {
     icaltime_span span;
@@ -1074,20 +913,6 @@ icaltime_span icaltime_span_new(struct icaltimetype dtstart, struct icaltimetype
     return span;
 }
 
-/** @brief Returns true if the two spans overlap
- *
- *  @param s1         1st span to test
- *  @param s2         2nd span to test
- *  @return           boolean value
- *
- *  The result is calculated by testing if the start time of s1 is contained
- *  by the s2 span, or if the end time of s1 is contained by the s2 span.
- *
- *  Also returns true if the spans are equal.
- *
- *  Note, this will return false if the spans are adjacent.
- */
-
 int icaltime_span_overlaps(icaltime_span *s1, icaltime_span *s2)
 {
     /* s1->start in s2 */
@@ -1112,15 +937,6 @@ int icaltime_span_overlaps(icaltime_span *s1, icaltime_span *s2)
     return 0;
 }
 
-/** @brief Returns true if the span is totally within the containing
- *  span
- *
- *  @param s          The span to test for.
- *  @param container  The span to test against.
- *  @return           boolean value.
- *
- */
-
 int icaltime_span_contains(icaltime_span *s, icaltime_span *container)
 {
     if ((s->start >= container->start && s->start < container->end) &&
diff --git a/src/libical/icaltime.h b/src/libical/icaltime.h
index 944020f8..e788e25e 100644
--- a/src/libical/icaltime.h
+++ b/src/libical/icaltime.h
@@ -119,28 +119,75 @@ struct icaltimetype
 
 typedef struct icaltimetype icaltimetype;
 
-/** Returns a null time, which indicates no time has been set.
-    This time represents the beginning of the epoch. */
+/**     @brief Constructor.
+ *
+ *      @returns A null time, which indicates no time has been set.
+ *      This time represents the beginning of the epoch.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_null_time(void);
 
-/** Returns a null date. */
+/**     @brief Constructor.
+ *
+ *      @returns A null date, which indicates no time has been set.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_null_date(void);
 
-/** Returns the current time in the given timezone, as an icaltimetype. */
+/**     @brief Convenience constructor.
+ *
+ * @returns The current time in the given timezone, as an icaltimetype.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_current_time_with_zone(const icaltimezone *zone);
 
-/** Returns the current day as an icaltimetype, with is_date set. */
+/**     @brief Convenience constructor.
+ *
+ * @returns The current day as an icaltimetype, with is_date set.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_today(void);
 
-/** Converts seconds past UNIX epoch to a timetype, using timezones. */
+/**     @brief Constructor.
+ *
+ *      @param tm The time expressed as seconds past UNIX epoch
+ *      @param is_date Boolean: 1 means we should treat tm as a DATE
+ *      @param zone The timezone tm is in, NULL means to treat tm as a
+ *              floating time
+ *
+ *      Returns a new icaltime instance, initialized to the given time,
+ *      optionally using the given timezone.
+ *
+ *      If the caller specifies the is_date param as TRUE, the returned
+ *      object is of DATE type, otherwise the input is meant to be of
+ *      DATE-TIME type.
+ *      If the zone is not specified (NULL zone param) the time is taken
+ *      to be floating, that is, valid in any timezone. Note that, in
+ *      addition to the uses specified in [RFC5545], this can be used
+ *      when doing simple math on couples of times.
+ *      If the zone is specified (UTC or otherwise), it's stored in the
+ *      object and it's used as the native timezone for this object.
+ *      This means that the caller can convert this time to a different
+ *      target timezone with no need to store the source timezone.
+ *
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_from_timet_with_zone(const time_t tm,
                                                                       const int is_date,
                                                                       const icaltimezone *zone);
 
-/** creates a time from an ISO format string. */
+/**     @brief Contructor.
+ *
+ * Creates a time from an ISO format string.
+ *
+ * @todo If the given string specifies a DATE-TIME not in UTC, there
+ *       is no way to know if this is a floating time or really refers to a
+ *       timezone. We should probably add a new constructor:
+ *       icaltime_from_string_with_zone()
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_from_string(const char *str);
 
-/** Creates a new time, given a day of year and a year. */
+/**     @brief Contructor.
+ *
+ *      Creates a new time, given a day of year and a year.
+ *
+ *      Note that Jan 1 is day #1, not 0.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_from_day_of_year(const int doy, const int year);
 
 /**
@@ -152,13 +199,31 @@ LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_from_day_of_year(const int doy,
  */
 LIBICAL_ICAL_EXPORT time_t icaltime_as_timet(const struct icaltimetype);
 
-/** Returns the time as seconds past the UNIX epoch, using timezones. */
+/**     @brief Returns the time as seconds past the UNIX epoch, using the
+ *      given timezone.
+ *
+ *      This convenience method combines a call to icaltime_convert_to_zone()
+ *      with a call to icaltime_as_timet().
+ *      If the input timezone is null, no conversion is done; that is, the
+ *      time is simply returned as time_t in its native timezone.
+ */
 LIBICAL_ICAL_EXPORT time_t icaltime_as_timet_with_zone(const struct icaltimetype tt,
                                                        const icaltimezone *zone);
 
-/** Returns a string represention of the time, in RFC5545 format. */
+/**
+ * @brief Returns a string represention of the time, in RFC5545 format.
+ *
+ * @par Ownership
+ * The created string is owned by libical.
+ */
 LIBICAL_ICAL_EXPORT const char *icaltime_as_ical_string(const struct icaltimetype tt);
 
+/**
+ * @brief Returns a string represention of the time, in RFC5545 format.
+ *
+ * @par Ownership
+ * The string is owned by the caller.
+ */
 LIBICAL_ICAL_EXPORT char *icaltime_as_ical_string_r(const struct icaltimetype tt);
 
 /** @brief Returns the timezone. */
@@ -167,79 +232,179 @@ LIBICAL_ICAL_EXPORT const icaltimezone *icaltime_get_timezone(const struct icalt
 /** @brief Returns the tzid, or NULL for a floating time. */
 LIBICAL_ICAL_EXPORT const char *icaltime_get_tzid(const struct icaltimetype t);
 
-/** @brief Sets the timezone. */
+/**     @brief Sets the timezone.
+ *
+ *      Forces the icaltime to be interpreted relative to another timezone.
+ *      If you need to do timezone conversion, applying offset adjustments,
+ *      then you should use icaltime_convert_to_zone instead.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_set_timezone(struct icaltimetype *t,
                                                               const icaltimezone *zone);
 
-/** Returns the day of the year of the given time. */
+/**
+ *      @brief Returns the day of the year, counting from 1 (Jan 1st).
+ */
 LIBICAL_ICAL_EXPORT int icaltime_day_of_year(const struct icaltimetype t);
 
-/** Returns the day of the week of the given time. Sunday is 1. */
+/** @brief Returns the day of the week of the given time.
+ *
+ * Sunday is 1, and Saturday is 7.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_day_of_week(const struct icaltimetype t);
 
-/** Returns the day of the year for the first day of the week that the
-   given time is within. */
+/** Returns the day of the year for the first day of the week . */
+/** @brief Returns the day of the year for the first day of the week
+ *  that the given time is within.
+ *
+ *  This uses the first day of the week that contains the given time,
+ *  which is a Sunday. It returns the day of the year for the resulting
+ *  day.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_start_doy_week(const struct icaltimetype t, int fdow);
 
-/** Returns the week number for the week the given time is within. */
+/** @brief Returns the week number for the week the given time is within.
+ *
+ * @todo Doesn't take into account the start day of the
+ * week. strftime assumes that weeks start on Monday.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_week_number(const struct icaltimetype t);
 
-/** Returns true if the time is null. */
+/** @brief Returns true if the time is null. */
 LIBICAL_ICAL_EXPORT int icaltime_is_null_time(const struct icaltimetype t);
 
-/** Returns false if the time is clearly invalid, but is not null. This
-   is usually the result of creating a new time type buy not clearing
-   it, or setting one of the flags to an illegal value. */
+/**
+ *      @brief Returns false if the time is clearly invalid, but is not null.
+ *
+ *      This is usually the result of creating a new time type but not
+ *      clearing it, or setting one of the flags to an illegal value.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_is_valid_time(const struct icaltimetype t);
 
-/** @brief Returns true if time is of DATE type, false if DATE-TIME. */
+/**     @brief Returns true if time is a DATE.
+ *
+ * The options are DATE type, which returns true, or DATE-TIME, which
+ * returns false.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_is_date(const struct icaltimetype t);
 
-/** @brief Returns true if time is relative to UTC zone. */
+/**     @brief Returns true if the time is relative to UTC zone.
+ *
+ *      @todo  We should only check the zone.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_is_utc(const struct icaltimetype t);
 
-/** Returns -1, 0, or 1 to indicate that a is less than b, a equals b, or a is greater than b. */
+/**
+ *      @brief Returns -1, 0, or 1 to indicate that a is less than b, a
+ *      equals b, or a is greater than b.
+ *
+ *      This converts both times to the UTC timezone and compares them.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_compare(const struct icaltimetype a, const struct icaltimetype b);
 
-/** like icaltime_compare, but only use the date parts. */
+/** @brief Like icaltime_compare, but only use the date parts.
+ *
+ * This converts both times to the UTC timezone and compares their date
+ * components.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_compare_date_only(const struct icaltimetype a,
                                                    const struct icaltimetype b);
 
-/** like icaltime_compare, but only use the date parts. */
+/** @brief Like icaltime_compare, but only use the date parts; accepts
+ *  timezone.
+ *
+ * This converts both times to the given timezone and compares their date
+ * components.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_compare_date_only_tz(const struct icaltimetype a,
                                                       const struct icaltimetype b,
                                                       icaltimezone *tz);
 
 /** Adds or subtracts a number of days, hours, minutes and seconds. */
+/**     @brief Internal, shouldn't be part of the public API
+ *
+ *      Adds or subtracts a time from a icaltimetype. This time is given
+ *      as a number of days, hours, minutes and seconds.
+ *
+ *      @note This function is exactly the same as
+ *      icaltimezone_adjust_change() except for the type of the first
+ *      parameter.
+ */
 LIBICAL_ICAL_EXPORT void icaltime_adjust(struct icaltimetype *tt,
                                          const int days, const int hours,
                                          const int minutes, const int seconds);
 
-/** Normalizes the icaltime, so that all fields are within the normal range. */
+/**
+ *      @brief Normalizes the icaltime, so all of the time components
+ *      are in their normal ranges.
+ *
+ *      For instance, given a time with minutes=70, the minutes will be
+ *      reduces to 10, and the hour incremented. This allows the caller
+ *      to do arithmetic on times without worrying about overflow or
+ *      underflow.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_normalize(const struct icaltimetype t);
 
-/** converts tt, of timezone tzid, into a utc time. Does nothing if the
-   time is already UTC.  */
+/**     @brief Converts time to a given timezone.
+ *
+ *      Converts a time from its native timezone to a given timezone.
+ *
+ *      If tt is a date, the returned time is an exact
+ *      copy of the input. If it's a floating time, the returned object
+ *      represents the same time translated to the given timezone.
+ *      Otherwise the time will be converted to the new
+ *      time zone, and its native timezone set to the right timezone.
+ */
 LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_convert_to_zone(const struct icaltimetype tt,
                                                                  icaltimezone *zone);
 
 /** Returns the number of days in the given month. */
 LIBICAL_ICAL_EXPORT int icaltime_days_in_month(const int month, const int year);
 
-/** Returns whether you've specified a leapyear or not. */
+/**
+ * @brief Returns whether the specified year is a leap year.
+ *
+ * Year is the normal year, e.g. 2001.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_is_leap_year(const int year);
 
 /** Returns the number of days in this year. */
 LIBICAL_ICAL_EXPORT int icaltime_days_in_year(const int year);
 
-/** @brief calculates an icaltimespan given a start and end time. */
+/**
+ *  @brief Builds an icaltimespan given a start time, end time and busy value.
+ *
+ *  @param dtstart   The beginning time of the span, can be a date-time
+ *                   or just a date.
+ *  @param dtend     The end time of the span.
+ *  @param is_busy   A boolean value, 0/1.
+ *  @returns          A span using the supplied values. The times are specified in UTC.
+ */
 LIBICAL_ICAL_EXPORT struct icaltime_span icaltime_span_new(struct icaltimetype dtstart,
                                                            struct icaltimetype dtend, int is_busy);
 
-/** @brief Returns true if the two spans overlap. */
+/** @brief Returns true if the two spans overlap.
+ *
+ *  @param s1         First span to test
+ *  @param s2         Second span to test
+ *  @return           boolean value
+ *
+ *  The result is calculated by testing if the start time of s1 is contained
+ *  by the s2 span, or if the end time of s1 is contained by the s2 span.
+ *
+ *  Also returns true if the spans are equal.
+ *
+ *  Note, this will return false if the spans are adjacent.
+ */
 LIBICAL_ICAL_EXPORT int icaltime_span_overlaps(icaltime_span *s1, icaltime_span *s2);
 
-/** @brief Returns true if the span is totally within the containing span. */
+/** @brief Returns true if the span is totally within the containing
+ *  span.
+ *
+ *  @param s          The span to test for.
+ *  @param container  The span to test against.
+ *  @return           boolean value.
+ *
+ */
 LIBICAL_ICAL_EXPORT int icaltime_span_contains(icaltime_span *s, icaltime_span *container);
 
 #endif /* !ICALTIME_H */
diff --git a/src/libical/icaltimezone.c b/src/libical/icaltimezone.c
index 4be7cb94..9a1c641c 100644
--- a/src/libical/icaltimezone.c
+++ b/src/libical/icaltimezone.c
@@ -189,7 +189,6 @@ const char *icaltimezone_tzid_prefix(void)
     return s_ical_tzid_prefix;
 }
 
-/** @brief Creates a new icaltimezone. */
 icaltimezone *icaltimezone_new(void)
 {
     icaltimezone *zone;
@@ -239,7 +238,6 @@ icaltimezone *icaltimezone_copy(icaltimezone *originalzone)
     return zone;
 }
 
-/** @brief Frees all memory used for the icaltimezone. */
 void icaltimezone_free(icaltimezone *zone, int free_struct)
 {
     icaltimezone_reset(zone);
@@ -334,7 +332,6 @@ static int icaltimezone_get_vtimezone_properties(icaltimezone *zone, icalcompone
     return 1;
 }
 
-/** @brief Gets the LOCATION or X-LIC-LOCATION property from a VTIMEZONE. */
 char *icaltimezone_get_location_from_vtimezone(icalcomponent *component)
 {
     icalproperty *prop;
@@ -362,11 +359,6 @@ char *icaltimezone_get_location_from_vtimezone(icalcomponent *component)
     return NULL;
 }
 
-/** Gets the TZNAMEs used for the last STANDARD & DAYLIGHT components
-   in a VTIMEZONE. If both STANDARD and DAYLIGHT components use the
-   same TZNAME, it returns that. If they use different TZNAMEs, it
-   formats them like "EST/EDT". The returned string should be freed by
-   the caller. */
 char *icaltimezone_get_tznames_from_vtimezone(icalcomponent *component)
 {
     icalcomponent *comp;
@@ -804,13 +796,6 @@ void icaltimezone_convert_time(struct icaltimetype *tt,
     icaltime_adjust(tt, 0, 0, 0, utc_offset);
 }
 
-/** @brief Calculates the UTC offset of a given local time in the given
- * timezone.
- *
- * It is the number of seconds to add to UTC to get local
- * time.  The is_daylight flag is set to 1 if the time is in
- * daylight-savings time.
- */
 int icaltimezone_get_utc_offset(icaltimezone *zone, struct icaltimetype *tt, int *is_daylight)
 {
     icaltimezonechange *zone_change, *prev_zone_change, tt_change, tmp_change;
@@ -968,12 +953,6 @@ int icaltimezone_get_utc_offset(icaltimezone *zone, struct icaltimetype *tt, int
     return utc_offset_change;
 }
 
-/** @brief Calculates the UTC offset of a given UTC time in the given timezone.
- *
- * It is the number of seconds to add to UTC to get local
- * time.  The @p is_daylight flag is set to 1 if the time is in
- * daylight-savings time.
- */
 int icaltimezone_get_utc_offset_of_utc_time(icaltimezone *zone,
                                             struct icaltimetype *tt, int *is_daylight)
 {
@@ -1214,7 +1193,6 @@ const char *icaltimezone_get_tznames(icaltimezone *zone)
     return zone->tznames;
 }
 
-/** @brief Returns the latitude of a builtin timezone. */
 double icaltimezone_get_latitude(icaltimezone *zone)
 {
     /* If this is a floating time, without a timezone, return 0. */
@@ -1226,7 +1204,6 @@ double icaltimezone_get_latitude(icaltimezone *zone)
     return zone->latitude;
 }
 
-/** @brief Returns the longitude of a builtin timezone. */
 double icaltimezone_get_longitude(icaltimezone *zone)
 {
     /* If this is a floating time, without a timezone, return 0. */
@@ -1238,7 +1215,6 @@ double icaltimezone_get_longitude(icaltimezone *zone)
     return zone->longitude;
 }
 
-/** @brief Returns the VTIMEZONE component of a timezone. */
 icalcomponent *icaltimezone_get_component(icaltimezone *zone)
 {
     /* If this is a floating time, without a timezone, return NULL. */
@@ -1250,23 +1226,12 @@ icalcomponent *icaltimezone_get_component(icaltimezone *zone)
     return zone->component;
 }
 
-/** @brief Sets the VTIMEZONE component of an icaltimezone, initializing the
- * tzid, location & tzname fields.
- *
- * @returns 1 on success or 0 on failure, i.e.  no TZID was found.
- */
 int icaltimezone_set_component(icaltimezone *zone, icalcomponent *comp)
 {
     icaltimezone_reset(zone);
     return icaltimezone_get_vtimezone_properties(zone, comp);
 }
 
-/** @brief Returns the timezone name to display to the user.
- *
- * We prefer to use the Olson city name, but fall back on the TZNAME, or finally
- * the TZID. We don't want to use "" as it may be wrongly interpreted as a
- * floating time. Do not free the returned string.
- */
 const char *icaltimezone_get_display_name(icaltimezone *zone)
 {
     const char *display_name;
@@ -1342,13 +1307,6 @@ void icaltimezone_array_free(icalarray *timezones)
  * BUILTIN TIMEZONE HANDLING
  */
 
-/** @brief Returns an icalarray of icaltimezone structs, one for each builtin
-   timezone.
- *
- * This will load and parse the zones.tab file to get the
- * timezone names and their coordinates. It will not load the
- * VTIMEZONE data for any timezones.
- */
 icalarray *icaltimezone_get_builtin_timezones(void)
 {
     if (!builtin_timezones)
@@ -1357,14 +1315,12 @@ icalarray *icaltimezone_get_builtin_timezones(void)
     return builtin_timezones;
 }
 
-/** @brief Releases builtin timezone memory. */
 void icaltimezone_free_builtin_timezones(void)
 {
     icaltimezone_array_free(builtin_timezones);
     builtin_timezones = 0;
 }
 
-/** @brief Returns a single builtin timezone, given its Olson city name. */
 icaltimezone *icaltimezone_get_builtin_timezone(const char *location)
 {
     icalcomponent *comp;
@@ -1463,7 +1419,6 @@ static int get_offset(icaltimezone *zone)
     return offset;
 }
 
-/** @brief Returns a single builtin timezone, given its offset from UTC. */
 icaltimezone *icaltimezone_get_builtin_timezone_from_offset(int offset, const char *tzname)
 {
     icaltimezone *zone = NULL;
@@ -1495,7 +1450,6 @@ icaltimezone *icaltimezone_get_builtin_timezone_from_offset(int offset, const ch
     return NULL;
 }
 
-/** @brief Returns a single builtin timezone, given its TZID. */
 icaltimezone *icaltimezone_get_builtin_timezone_from_tzid(const char *tzid)
 {
 #if defined(USE_BUILTIN_TZDATA)
@@ -1553,7 +1507,6 @@ icaltimezone *icaltimezone_get_builtin_timezone_from_tzid(const char *tzid)
     }
 }
 
-/** @brief Returns the special UTC timezone. */
 icaltimezone *icaltimezone_get_utc_timezone(void)
 {
     if (!builtin_timezones)
@@ -1908,21 +1861,6 @@ static char *icaltimezone_load_get_line_fn(char *s, size_t size, void *data)
  * DEBUGGING
  */
 
-/**
- * Outputs a list of timezone changes for the given timezone to the
- * given file, up to the maximum year given. We compare this output with the
- * output from 'vzic --dump-changes' to make sure that we are consistent.
- * (vzic is the Olson timezone database to VTIMEZONE converter.)
- *
- * The output format is:
- *
- *      Zone-Name [tab] Date [tab] Time [tab] UTC-Offset
- *
- * The Date and Time fields specify the time change in UTC.
- *
- * The UTC Offset is for local (wall-clock) time. It is the amount of time
- * to add to UTC to get local time.
- */
 int icaltimezone_dump_changes(icaltimezone *zone, int max_year, FILE *fp)
 {
     static const char *months[] = { "Jan", "Feb", "Mar", "Apr", "May", "Jun",
diff --git a/src/libical/icaltimezone.h b/src/libical/icaltimezone.h
index ee678e5b..0c7e56a1 100644
--- a/src/libical/icaltimezone.h
+++ b/src/libical/icaltimezone.h
@@ -40,13 +40,15 @@ typedef struct _icaltimezone icaltimezone;
  * Creating/Destroying individual icaltimezones.
  */
 
-/** Creates a new icaltimezone. */
+/** @brief Creates a new icaltimezone. */
 LIBICAL_ICAL_EXPORT icaltimezone *icaltimezone_new(void);
 
 LIBICAL_ICAL_EXPORT icaltimezone *icaltimezone_copy(icaltimezone *originalzone);
 
-/** Frees all memory used for the icaltimezone. Set free_struct to free the
-   icaltimezone struct as well. */
+/** @brief Frees all memory used for the icaltimezone.
+ * @param zone The icaltimezone to be freed
+ * @param free_struct Whether to free the icaltimezone struct as well
+ */
 LIBICAL_ICAL_EXPORT void icaltimezone_free(icaltimezone *zone, int free_struct);
 
 /** Sets the prefix to be used for tzid's generated from system tzdata.
@@ -60,23 +62,29 @@ LIBICAL_ICAL_EXPORT void icaltimezone_set_tzid_prefix(const char *new_prefix);
  * Accessing timezones.
  */
 
-/** Frees any builtin timezone information **/
+/** @brief Releases builtin timezone memory. */
 LIBICAL_ICAL_EXPORT void icaltimezone_free_builtin_timezones(void);
 
-/** Returns the array of builtin icaltimezones. */
+/** @brief Returns an icalarray of icaltimezone structs, one for each builtin
+   timezone.
+ *
+ * This will load and parse the zones.tab file to get the
+ * timezone names and their coordinates. It will not load the
+ * VTIMEZONE data for any timezones.
+ */
 LIBICAL_ICAL_EXPORT icalarray *icaltimezone_get_builtin_timezones(void);
 
-/** Returns a single builtin timezone, given its Olson city name. */
+/** @brief Returns a single builtin timezone, given its Olson city name. */
 LIBICAL_ICAL_EXPORT icaltimezone *icaltimezone_get_builtin_timezone(const char *location);
 
-/** Returns a single builtin timezone, given its offset. */
+/** @brief Returns a single builtin timezone, given its offset from UTC. */
 LIBICAL_ICAL_EXPORT icaltimezone *icaltimezone_get_builtin_timezone_from_offset(int offset,
                                                                                 const char *tzname);
 
-/** Returns a single builtin timezone, given its TZID. */
+/** @brief Returns a single builtin timezone, given its TZID. */
 LIBICAL_ICAL_EXPORT icaltimezone *icaltimezone_get_builtin_timezone_from_tzid(const char *tzid);
 
-/** Returns the UTC timezone. */
+/** @brief Returns the UTC timezone. */
 LIBICAL_ICAL_EXPORT icaltimezone *icaltimezone_get_utc_timezone(void);
 
 /** Returns the TZID of a timezone. */
@@ -91,20 +99,28 @@ LIBICAL_ICAL_EXPORT const char *icaltimezone_get_location(icaltimezone *zone);
    may also return NULL. */
 LIBICAL_ICAL_EXPORT const char *icaltimezone_get_tznames(icaltimezone *zone);
 
-/** Returns the latitude of a builtin timezone. */
+/** @brief Returns the latitude of a builtin timezone. */
 LIBICAL_ICAL_EXPORT double icaltimezone_get_latitude(icaltimezone *zone);
 
-/** Returns the longitude of a builtin timezone. */
+/** @brief Returns the longitude of a builtin timezone. */
 LIBICAL_ICAL_EXPORT double icaltimezone_get_longitude(icaltimezone *zone);
 
-/** Returns the VTIMEZONE component of a timezone. */
+/** @brief Returns the VTIMEZONE component of a timezone. */
 LIBICAL_ICAL_EXPORT icalcomponent *icaltimezone_get_component(icaltimezone *zone);
 
-/** Sets the VTIMEZONE component of an icaltimezone, initializing the tzid,
-   location & tzname fields. It returns 1 on success or 0 on failure, i.e.
-   no TZID was found. */
+/** @brief Sets the VTIMEZONE component of an icaltimezone, initializing the
+ * tzid, location & tzname fields.
+ *
+ * @returns 1 on success or 0 on failure, i.e.  no TZID was found.
+ */
 LIBICAL_ICAL_EXPORT int icaltimezone_set_component(icaltimezone *zone, icalcomponent *comp);
 
+/** @brief Returns the timezone name to display to the user.
+ *
+ * We prefer to use the Olson city name, but fall back on the TZNAME, or finally
+ * the TZID. We don't want to use "" as it may be wrongly interpreted as a
+ * floating time. Do not free the returned string.
+ */
 LIBICAL_ICAL_EXPORT const char *icaltimezone_get_display_name(icaltimezone *zone);
 
 /*
@@ -119,17 +135,22 @@ LIBICAL_ICAL_EXPORT void icaltimezone_convert_time(struct icaltimetype *tt,
  * Getting offsets from UTC.
  */
 
-/** Calculates the UTC offset of a given local time in the given
-   timezone.  It is the number of seconds to add to UTC to get local
-   time.  The is_daylight flag is set to 1 if the time is in
-   daylight-savings time. */
+/** @brief Calculates the UTC offset of a given local time in the given
+ * timezone.
+ *
+ * It is the number of seconds to add to UTC to get local
+ * time.  The is_daylight flag is set to 1 if the time is in
+ * daylight-savings time.
+ */
 LIBICAL_ICAL_EXPORT int icaltimezone_get_utc_offset(icaltimezone *zone,
                                                     struct icaltimetype *tt, int *is_daylight);
 
-/** Calculates the UTC offset of a given UTC time in the given
-   timezone.  It is the number of seconds to add to UTC to get local
-   time.  The is_daylight flag is set to 1 if the time is in
-   daylight-savings time. */
+/** @brief Calculates the UTC offset of a given UTC time in the given timezone.
+ *
+ * It is the number of seconds to add to UTC to get local
+ * time.  The @p is_daylight flag is set to 1 if the time is in
+ * daylight-savings time.
+ */
 LIBICAL_ICAL_EXPORT int icaltimezone_get_utc_offset_of_utc_time(icaltimezone *zone,
                                                                 struct icaltimetype *tt,
                                                                 int *is_daylight);
@@ -150,8 +171,15 @@ LIBICAL_ICAL_EXPORT void icaltimezone_array_free(icalarray *timezones);
 LIBICAL_ICAL_EXPORT void icaltimezone_expand_vtimezone(icalcomponent *comp,
                                                        int end_year, icalarray *changes);
 
+/** @brief Gets the LOCATION or X-LIC-LOCATION property from a VTIMEZONE. */
 LIBICAL_ICAL_EXPORT char *icaltimezone_get_location_from_vtimezone(icalcomponent *component);
 
+/** @brief Gets the TZNAMEs used for the last STANDARD & DAYLIGHT
+ * components in a VTIMEZONE.
+ *
+ * If both STANDARD and DAYLIGHT components use the same TZNAME, it
+ * returns that. If they use different TZNAMEs, it formats them like
+ * "EST/EDT". The returned string should be freed by the caller. */
 LIBICAL_ICAL_EXPORT char *icaltimezone_get_tznames_from_vtimezone(icalcomponent *component);
 
 /*
@@ -187,11 +215,26 @@ LIBICAL_ICAL_EXPORT void icaltimezone_set_builtin_tzdata(int set);
 LIBICAL_ICAL_EXPORT int icaltimezone_get_builtin_tzdata(void);
 
 /*
- * @par Debugging Output.
+ * Debugging Output.
  */
 
-/** Dumps information about changes in the timezone up to and including
-   max_year. */
+/**
+ * @brief Outputs a list of timezone changes for the given timezone to the
+ * given file, up to the maximum year given.
+ *
+ * We compare this output with the output from 'vzic --dump-changes' to
+ * make sure that we are consistent. (vzic is the Olson timezone
+ * database to VTIMEZONE converter.)
+ *
+ * The output format is:
+ *
+ *      Zone-Name [tab] Date [tab] Time [tab] UTC-Offset
+ *
+ * The Date and Time fields specify the time change in UTC.
+ *
+ * The UTC Offset is for local (wall-clock) time. It is the amount of time
+ * to add to UTC to get local time.
+ */
 LIBICAL_ICAL_EXPORT int icaltimezone_dump_changes(icaltimezone *zone, int max_year, FILE *fp);
 
 /* For the library only -- do not make visible */