From ce3e92c4ef3cfbf3fc19a9c081600593f464c861 Mon Sep 17 00:00:00 2001 From: Michael McClurg Date: Sat, 18 Jul 2020 16:08:39 -0600 Subject: Unify all visible docstrings to .h files Reduces redundancy and conflicting information --- src/libical/icalcomponent.c | 164 ------------------------------- src/libical/icalcomponent.h | 192 +++++++++++++++++++++++++++++++++++-- src/libical/icalenums.c | 10 -- src/libical/icalenums.h | 10 ++ src/libical/icalparameter.c | 19 ++-- src/libical/icalparameter.h | 4 +- src/libical/icalparser.c | 6 +- src/libical/icalparser.h | 1 + src/libical/icalproperty.c | 33 ------- src/libical/icalproperty.h | 30 ++++++ src/libical/icalrecur.c | 51 ++++------ src/libical/icalrecur.h | 76 +++++++++++---- src/libical/icaltime.c | 186 +---------------------------------- src/libical/icaltime.h | 229 +++++++++++++++++++++++++++++++++++++------- src/libical/icaltimezone.c | 62 ------------ src/libical/icaltimezone.h | 95 +++++++++++++----- 16 files changed, 574 insertions(+), 594 deletions(-) (limited to 'src/libical') 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 ab. - * - * 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 */ -- cgit v1.2.1