diff options
author | Allen Winter <allen.winter@kdab.com> | 2022-06-09 17:14:26 -0400 |
---|---|---|
committer | Allen Winter <allen.winter@kdab.com> | 2022-06-09 17:14:26 -0400 |
commit | 1b97dd16107943aa84558d26f11b92265c71627a (patch) | |
tree | 60211ead8dab74dcbd3f54215582cd669836c8dd /src | |
parent | 29fade679cfa48f415ec3504a1a1832fa4b211de (diff) | |
download | libical-git-1b97dd16107943aa84558d26f11b92265c71627a.tar.gz |
improve doxgen documentation. fix doxygen warnings
Diffstat (limited to 'src')
-rw-r--r-- | src/libical/icalarray.h | 32 | ||||
-rw-r--r-- | src/libical/icalattach.h | 44 | ||||
-rw-r--r-- | src/libical/icalcomponent.h | 4 | ||||
-rw-r--r-- | src/libical/icalduration.h | 32 | ||||
-rw-r--r-- | src/libical/icalerror.h | 40 | ||||
-rw-r--r-- | src/libical/icalmemory.h | 24 | ||||
-rw-r--r-- | src/libical/icalparameter.h | 114 | ||||
-rw-r--r-- | src/libical/icalparser.h | 52 | ||||
-rw-r--r-- | src/libical/icalperiod.h | 14 | ||||
-rw-r--r-- | src/libical/icalproperty.h | 2 | ||||
-rw-r--r-- | src/libical/icalrestriction.h | 6 | ||||
-rw-r--r-- | src/libical/icaltime.h | 4 | ||||
-rw-r--r-- | src/libicalss/icalspanlist.c | 12 | ||||
-rw-r--r-- | src/libicalss/icalspanlist.h | 8 |
14 files changed, 194 insertions, 194 deletions
diff --git a/src/libical/icalarray.h b/src/libical/icalarray.h index 2fc9fb26..32ff4ae7 100644 --- a/src/libical/icalarray.h +++ b/src/libical/icalarray.h @@ -42,29 +42,29 @@ struct _icalarray }; /** - * @brief Creates a new ::icalarray object. + * @brief Creates a new icalarray object. * @param element_size The size of the elements to be held by the array * @param increment_size How many extra elements worth of space to allocate on expansion - * @return The new ::icalarray object + * @return The new icalarray object * @sa icalarray_free() * - * Creates a new ::icalarray object. The parameter @a element_size determines + * Creates a new icalarray object. The parameter @a element_size determines * the size of the elements that the array will hold (in bytes). The parameter * @a increment_size determines how many extra elements to be allocated when * expanding the array for performance reasons (expansions are expensive, since * it involves copying all existing elements). * * @par Error handling - * If @a element_size or @a increment_size is not at least 1, using the ::icalarray + * If @a element_size or @a increment_size is not at least 1, using the icalarray * object results in undefined behaviour. If there is an error while creating the * object, it returns `NULL` and sets ::icalerrno to ::ICAL_NEWFAILED_ERROR. * * @par Ownership - * The returned ::icalarray object is owned by the caller of the function, + * The returned icalarray object is owned by the caller of the function, * and needs to be released properly after it's no longer needed with * icalarray_free(). * - * ### Usage + * @par Usage * ```c * // create new array * icalarray *array = icalarray_new(sizeof(int), 1); @@ -81,11 +81,11 @@ struct _icalarray LIBICAL_ICAL_EXPORT icalarray *icalarray_new(size_t element_size, size_t increment_size); /** - * @brief Copies an existing ::icalarray and its elements, creating a new one. + * @brief Copies an existing icalarray and its elements, creating a new one. * @param array The array to copy * @return A new array, holding all the elements of @a array * - * Creates a new ::icalarray object, copying all the existing elements from + * Creates a new icalarray object, copying all the existing elements from * @a array as well as its properties (such as @a element_size and * @a increment_size) over. * @@ -98,7 +98,7 @@ LIBICAL_ICAL_EXPORT icalarray *icalarray_new(size_t element_size, size_t increme * The created copy is owned by the caller of the function, and needs to * be released with icalarray_free() after it's no longer being used. * - * ### Usage + * @par Usage * ```c * // create new array * icalarray *array = icalarray_new(sizeof(int), 1); @@ -122,7 +122,7 @@ LIBICAL_ICAL_EXPORT icalarray *icalarray_copy(icalarray *array); * @brief Frees an array object and everything that it contains. * @param array The array to release * - * ### Example + * @par Example * ```c * // creating an array * icalarray *array = icalarray_new(sizeof(int), 1); @@ -149,7 +149,7 @@ LIBICAL_ICAL_EXPORT void icalarray_free(icalarray *array); * The @a element does not get consumed by the method, since it creates * a copy of it * - * ### Usage + * @par Usage * ```c * // create new array * icalarray *array = icalarray_new(sizeof(int), 1); @@ -176,7 +176,7 @@ LIBICAL_ICAL_EXPORT void icalarray_append(icalarray *array, const void *element) * If the array is empty, using this function results in undefined behaviour. * If the @a position is non-existent, it removes the last element. * - * ### Usage + * @par Usage * ```c * // create new array * icalarray *array = icalarray_new(sizeof(int), 2); @@ -227,10 +227,10 @@ LIBICAL_ICAL_EXPORT void icalarray_remove_element_at(icalarray *array, size_t po * results in undefined behaviour. * * @par Ownership - * The element is owned by the ::icalarray, it must not be freed by + * The element is owned by the icalarray, it must not be freed by * the user. * - * ### Usage + * @par Usage * ```c * // create new array * icalarray *array = icalarray_new(sizeof(int), 1); @@ -255,7 +255,7 @@ LIBICAL_ICAL_EXPORT void icalarray_remove_element_at(icalarray *array, size_t po LIBICAL_ICAL_EXPORT void *icalarray_element_at(icalarray *array, size_t position); /** - * @brief Sorts the elements of an ::icalarray using the given comparison function. + * @brief Sorts the elements of an icalarray using the given comparison function. * @param array The array to sort * @param compare The comparison function to use * @@ -263,7 +263,7 @@ LIBICAL_ICAL_EXPORT void *icalarray_element_at(icalarray *array, size_t position * Passing `NULL` as either @a array or @a compare results in undefined * behaviour. * - * ### Usage + * @par Usage * ```c * int compare_ints(const void *a, const void *b) { * return *((int*)a) - *((int*)b); diff --git a/src/libical/icalattach.h b/src/libical/icalattach.h index 9a606773..6eb7b851 100644 --- a/src/libical/icalattach.h +++ b/src/libical/icalattach.h @@ -23,7 +23,7 @@ * With the `ATTACH` property, the iCal standard defines a way to * associate a document object with a calendar component. * - * These are represented with ::icalattach objects in libical. + * These are represented with icalattach objects in libical. * This file contains functions to create and work with these * objects. */ @@ -37,7 +37,7 @@ * @typedef icalattach * @brief An iCal attach object representing a link to a document object. * - * Represents an association with a document object. ::icalattach objects + * Represents an association with a document object. icalattach objects * are reference counted, meaning that if the last reference to them is * removed (with icalattach_unref()), they are destroyed. */ @@ -54,9 +54,9 @@ typedef struct icalattach_impl icalattach; typedef void (*icalattach_free_fn_t) (char *data, void *user_data); /** - * @brief Creates new ::icalattach object from a URL. + * @brief Creates new icalattach object from a URL. * @param url The URL to create the object from - * @return An ::icalattach object with the given URL as association + * @return An icalattach object with the given URL as association * @sa icalattach_unref() * * @par Error handling @@ -65,12 +65,12 @@ typedef void (*icalattach_free_fn_t) (char *data, void *user_data); * returns `NULL` and sets `errno` to `ENOMEM`. * * @par Ownership - * The returned ::icalattach object is owned by the caller of the function. - * ::icalattach objects are reference counted, which means that after + * The returned icalattach object is owned by the caller of the function. + * icalattach objects are reference counted, which means that after * use, icalattach_unref() needs to be called to signal that they are * not used anymore. * - * ### Usage + * @par Usage * ```c * // creates new * icalattach *attach = icalattach_new_from_url("http://example.com"); @@ -86,11 +86,11 @@ typedef void (*icalattach_free_fn_t) (char *data, void *user_data); LIBICAL_ICAL_EXPORT icalattach *icalattach_new_from_url(const char *url); /** - * @brief Creates new ::icalattach object from data. - * @param data The data to create the ::icalattach from + * @brief Creates new icalattach object from data. + * @param data The data to create the icalattach from * @param free_fn The function to free the data * @param free_fn_data Data to pass to the @a free_fn - * @return An ::icalattach object with the given data + * @return An icalattach object with the given data * @sa icalattach_unref() * * @par Error handling @@ -99,8 +99,8 @@ LIBICAL_ICAL_EXPORT icalattach *icalattach_new_from_url(const char *url); * returns `NULL` and sets `errno` to `ENOMEM`. * * @par Ownership - * The returned ::icalattach object is owned by the caller of the function. - * ::icalattach objects are reference counted, which means that after + * The returned icalattach object is owned by the caller of the function. + * icalattach objects are reference counted, which means that after * use, icalattach_unref() needs to be called to signal that they are * not used anymore. */ @@ -109,7 +109,7 @@ LIBICAL_ICAL_EXPORT icalattach *icalattach_new_from_data(const char *data, void *free_fn_data); /** - * @brief Increments reference count of the ::icalattach. + * @brief Increments reference count of the icalattach. * @param attach The object to increase the reference count of * @sa icalattach_unref() * @@ -125,7 +125,7 @@ LIBICAL_ICAL_EXPORT icalattach *icalattach_new_from_data(const char *data, LIBICAL_ICAL_EXPORT void icalattach_ref(icalattach *attach); /** - * @brief Decrements reference count of the ::icalattach. + * @brief Decrements reference count of the icalattach. * @param attach The object to decrease the reference count of * @sa icalattach_ref() * @@ -140,7 +140,7 @@ LIBICAL_ICAL_EXPORT void icalattach_ref(icalattach *attach); * Calling this function releases the icalattach back to the library, * and it must not be used afterwards. * - * ### Usage + * @par Usage * ```c * // creates new * icalattach *attach = icalattach_new_from_url("http://example.com"); @@ -153,7 +153,7 @@ LIBICAL_ICAL_EXPORT void icalattach_unref(icalattach *attach); /** * @brief Determines if @a attach is an URL. - * @param attach the ::icalattach object to check + * @param attach the icalattach object to check * @return 1 if it is a URL, otherwise 0. * @sa icalattach_get_url() * @@ -161,7 +161,7 @@ LIBICAL_ICAL_EXPORT void icalattach_unref(icalattach *attach); * Returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR if * @a attach is `NULL`. * - * ### Usage + * @par Usage * ```c * // creates new * icalattach *attach = icalattach_new_from_url("http://example.com"); @@ -176,12 +176,12 @@ LIBICAL_ICAL_EXPORT void icalattach_unref(icalattach *attach); LIBICAL_ICAL_EXPORT int icalattach_get_is_url(icalattach *attach); /** - * @brief Returns the URL of the ::icalattach object. + * @brief Returns the URL of the icalattach object. * @param attach The object from which to return the URL * @return The URL of the object * @sa icalattach_get_is_url() * - * Returns the URL of the ::icalattach object. + * Returns the URL of the icalattach object. * * @par Error handling * Returns `NULL` and set ::icalerrno to ::ICAL_BADARG_ERROR if @@ -192,7 +192,7 @@ LIBICAL_ICAL_EXPORT int icalattach_get_is_url(icalattach *attach); * The string returned is owned by libical and must not be freed * by the caller. * - * # Usage + * @par Usage * ```c * // creates new * icalattach *attach = icalattach_new_from_url("http://example.com"); @@ -208,12 +208,12 @@ LIBICAL_ICAL_EXPORT int icalattach_get_is_url(icalattach *attach); LIBICAL_ICAL_EXPORT const char *icalattach_get_url(icalattach *attach); /** - * @brief Returns the data of the ::icalattach object. + * @brief Returns the data of the icalattach object. * @param attach The object from which to return the data * @return The data of the object * @sa icalattach_get_is_url() * - * Returns the URL of the ::icalattach object. + * Returns the URL of the icalattach object. * * @par Error handling * Returns `NULL` and set ::icalerrno to ::ICAL_BADARG_ERROR if diff --git a/src/libical/icalcomponent.h b/src/libical/icalcomponent.h index 70533a34..2b00fee7 100644 --- a/src/libical/icalcomponent.h +++ b/src/libical/icalcomponent.h @@ -449,8 +449,8 @@ LIBICAL_ICAL_EXPORT int icalproperty_recurrence_is_excluded(icalcomponent *comp, * * 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 + * 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, diff --git a/src/libical/icalduration.h b/src/libical/icalduration.h index 228dab7c..0c3fe6e8 100644 --- a/src/libical/icalduration.h +++ b/src/libical/icalduration.h @@ -50,7 +50,7 @@ struct icaldurationtype * @param t The duration in seconds * @return An ::icaldurationtype representing the duration @a t in seconds * - * ### Example + * @par Example * ```c * // create a new icaldurationtype with a duration of 60 seconds * struct icaldurationtype duration; @@ -71,7 +71,7 @@ LIBICAL_ICAL_EXPORT struct icaldurationtype icaldurationtype_from_int(int t); * When given bad input, it sets ::icalerrno to ::ICAL_MALFORMEDDATA_ERROR and * returns icaldurationtype_bad_duration(). * - * ### Usage + * @par Usage * ```c * // create a new icaldurationtype * struct icaldurationtype duration; @@ -88,7 +88,7 @@ LIBICAL_ICAL_EXPORT struct icaldurationtype icaldurationtype_from_string(const c * @param duration The duration to convert to seconds * @return An `int` representing the duration in seconds * - * ### Usage + * @par Usage * ```c * // create icaldurationtype with given duration * struct icaldurationtype duration; @@ -102,15 +102,15 @@ LIBICAL_ICAL_EXPORT int icaldurationtype_as_int(struct icaldurationtype duration /** * Converts an icaldurationtype into the iCal format as string. - * @param The icaldurationtype to convert to iCal format + * @param d is the icaldurationtype to convert to iCal format * @return A string representing duration @p d in iCal format * @sa icaldurationtype_as_ical_string_r() * - * @b Ownership + * @par Ownership * The string returned by this function is owned by the caller and needs to be * released with `free()` after it's no longer needed. * - * @b Usage + * @par Usage * ```c * // create new duration * struct icaldurationtype duration; @@ -128,15 +128,15 @@ LIBICAL_ICAL_EXPORT char *icaldurationtype_as_ical_string(struct icaldurationtyp /** * Converts an icaldurationtype into the iCal format as string. - * @param The icaldurationtype to convert to iCal format + * @param d is the icaldurationtype to convert to iCal format * @return A string representing duration @p d in iCal format * @sa icaldurationtype_as_ical_string() * - * @b Ownership + * @par Ownership * The string returned by this function is owned by libical and must not be * released by the caller of the function. * - * @b Usage + * @par Usage * ```c * // create new duration * struct icaldurationtype duration; @@ -153,7 +153,7 @@ LIBICAL_ICAL_EXPORT char *icaldurationtype_as_ical_string_r(struct icaldurationt * @return An ::icaldurationtype with a zero length * @sa icaldurationtype_is_null_duration() * - * ### Usage + * @par Usage * ```c * // create null duration * struct icaldurationtype duration; @@ -176,7 +176,7 @@ LIBICAL_ICAL_EXPORT struct icaldurationtype icaldurationtype_null_duration(void) * @return A bad duration * @sa icaldurationtype_is_bad_duration() * - * ### Usage + * @par Usage * ```c * // create bad duration * struct icaldurationtype duration; @@ -194,7 +194,7 @@ LIBICAL_ICAL_EXPORT struct icaldurationtype icaldurationtype_bad_duration(void); * @return 1 if the duration is a null duration, 0 otherwise * @sa icalduration_null_duration() * - * ### Usage + * @par Usage * ``` * // make null duration * struct icaldurationtype duration; @@ -212,7 +212,7 @@ LIBICAL_ICAL_EXPORT int icaldurationtype_is_null_duration(struct icaldurationtyp * @return 1 if the duration is a bad duration, 0 otherwise * @sa icalduration_bad_duration() * - * ### Usage + * @par Usage * ``` * // make bad duration * struct icaldurationtype duration; @@ -225,12 +225,12 @@ LIBICAL_ICAL_EXPORT int icaldurationtype_is_null_duration(struct icaldurationtyp LIBICAL_ICAL_EXPORT int icaldurationtype_is_bad_duration(struct icaldurationtype d); /** - * @brief Adds a duration to an ::icaltime object and returns the result. + * @brief Adds a duration to an icaltime object and returns the result. * @param t The time object to add the duration to * @param d The duration to add to the time object * @return The new ::icaltimetype which has been added the duration to * - * ### Example + * @par Example * ```c * struct icaltimetype time; * struct icaldurationtype duration; @@ -253,7 +253,7 @@ LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_add(struct icaltimetype t, * @return An ::icaldurationtype representing the duration the elapsed between * @a t1 and @a t2 * - * ### Usage + * @par Usage * ```c * struct icaltimetype t1 = icaltime_from_day_of_year(111, 2018); * struct icaltimetype t2 = icaltime_from_day_of_year(112, 2018); diff --git a/src/libical/icalerror.h b/src/libical/icalerror.h index 7fd1253a..90a6c438 100644 --- a/src/libical/icalerror.h +++ b/src/libical/icalerror.h @@ -118,7 +118,7 @@ typedef enum icalerrorenum * Yields a pointer to the current ::icalerrno value. This can * be used to access (read from and write to) it. * - * ### Examples + * @par Examples * ```c * assert(*icalerrno_return() == icalerrno); * ``` @@ -131,7 +131,7 @@ LIBICAL_ICAL_EXPORT icalerrorenum *icalerrno_return(void); * @note Pseudo-variable that can be used to access the current * ::icalerrno. * - * ### Usage + * @par Usage * ```c * if(icalerrno == ICAL_PARSE_ERROR) { * // ... @@ -149,7 +149,7 @@ LIBICAL_ICAL_EXPORT icalerrorenum *icalerrno_return(void); * @warning NOT THREAD SAFE: it is recommended that you do not change * this in a multithreaded program. * - * ### Usage + * @par Usage * ```c * icalerror_set_errors_are_fatal(true); // default * icalerror_set_errors_are_fatal(false); @@ -161,7 +161,7 @@ LIBICAL_ICAL_EXPORT void icalerror_set_errors_are_fatal(int fatal); * @brief Determine if errors are fatal * @return True if libical errors are fatal * - * ### Usage + * @par Usage * ```c * if(icalerror_get_errors_are_fatal()) { * // since errors are fatal, this will abort the @@ -179,7 +179,7 @@ LIBICAL_ICAL_EXPORT int icalerror_get_errors_are_fatal(void); * @brief Prints a formatted warning message to stderr * @param message Warning message to print * - * ### Usage + * @par Usage * ```c * icalerror_warn("Non-standard tag encountered"); * ``` @@ -196,7 +196,7 @@ LIBICAL_ICAL_EXPORT int icalerror_get_errors_are_fatal(void); /** * @brief Resets icalerrno to ::ICAL_NO_ERROR * - * ### Usage + * @par Usage * ```c * if(icalerrno == ICAL_PARSE_ERROR) { * // ignore parsing errors @@ -239,7 +239,7 @@ typedef enum icalerrorstate * The string that is returned is owned by the library and must not * be free'd() by the user. * - * ### Usage + * @par Usage * ```c * if(icalerrno != ICAL_NO_ERROR) { * printf("%s\n", icalerror_strerror(icalerrno)); @@ -259,7 +259,7 @@ LIBICAL_ICAL_EXPORT const char *icalerror_strerror(icalerrorenum e); * The string that is returned is owned by the library and must not * be free'd() by the user. * - * ### Usage + * @par Usage * ```c * if(icalerrno != ICAL_NO_ERROR) { * printf("%s\n", icalerror_perror()); @@ -272,7 +272,7 @@ LIBICAL_ICAL_EXPORT const char *icalerror_perror(void); * @brief Prints backtrace * @note Only works on systems that support it (HAVE_BACKTRACE enabled). * - * ### Usage + * @par Usage * ``` * if(icalerrno != ICAL_NO_ERROR) { * ical_bt(); @@ -289,7 +289,7 @@ LIBICAL_ICAL_EXPORT void ical_bt(void); * Sets the severity of a given error. For example, it can be used to * set the severity of an ::ICAL_PARSE_ERROR to be an ::ICAL_ERROR_NONFATAL. * - * ### Usage + * @par Usage * ```c * icalerror_set_error_state(ICAL_PARSE_ERROR, ICAL_ERROR_NONFATAL); * ``` @@ -312,7 +312,7 @@ LIBICAL_ICAL_EXPORT icalerrorstate icalerror_get_error_state(icalerrorenum error * If the error specified in @a str can't be found, instead * ::ICAL_UNKNOWN_ERROR is returned. * - * ### Usage + * @par Usage * ```c * assert(icalerror_error_from_string("PARSE") == ICAL_PARSE_ERROR); * assert(icalerror_error_from_string("NONSENSE") == ICAL_UNKNOWN_ERROR); @@ -330,7 +330,7 @@ LIBICAL_ICAL_EXPORT icalerrorenum icalerror_error_from_string(const char *str); * and ::ICAL_ERRORS_ARE_FATAL is true, it prints a warning to @a stderr * and aborts the process. * - * ### Usage + * @par Usage * ```c * icalerror_set_errno(ICAL_PARSE_ERROR); * ``` @@ -355,7 +355,7 @@ if(icalerror_get_error_state(x) == ICAL_ERROR_FATAL || \ * and ::ICAL_ERRORS_ARE_FATAL is true, it prints a warning to @a stderr * and aborts the process. * - * ### Usage + * @par Usage * ```c * icalerror_set_errno(ICAL_PARSE_ERROR); * ``` @@ -429,7 +429,7 @@ if (!(test)) { \ * test if the parameter @a arg is correct. If the assertion fails, * it sets ::icalerrno to ::ICAL_BADARG_ERROR. * - * ### Example + * @par Example * ```c * void test_function(icalcomponent *component) { * icalerror_check_arg(component != 0, "component"); @@ -453,7 +453,7 @@ if (!(test)) { \ * it sets ::icalerrno to ::ICAL_BADARG_ERROR and causes the enclosing * function to return `void`. * - * ### Example + * @par Example * ```c * void test_function(icalcomponent *component) { * icalerror_check_arg_rv(component != 0, "component"); @@ -478,7 +478,7 @@ if (!(test)) { \ * it sets ::icalerrno to ::ICAL_BADARG_ERROR and causes the enclosing * function to return `0`. * - * ### Example + * @par Example * ```c * int test_function(icalcomponent *component) { * icalerror_check_arg_rz(component != 0, "component"); @@ -505,7 +505,7 @@ if (!(test)) { \ * it aborts the process with `assert(0)` and causes the enclosing * function to return @a error. * - * ### Example + * @par Example * ```c * icalcomponent *test_function(icalcomponent *component) { * icalerror_check_arg_re(component != 0, "component", NULL); @@ -533,7 +533,7 @@ if (!(test)) { \ * it sets ::icalerrno to ::ICAL_BADARG_ERROR and causes the enclosing * function to return @a x. * - * ### Example + * @par Example * ```c * icalcomponent *test_function(icalcomponent *component) { * icalerror_check_arg_rx(component != 0, "component", NULL); @@ -560,7 +560,7 @@ if (!(test)) { \ * ::ICAL_ERROR_NONFATAL, and thus suppressed. Error states can be * restored with icalerror_restore(). * - * ### Usage + * @par Usage * ```c * // suppresses internal errors * icalerror_supress("INTERNAL"); @@ -575,7 +575,7 @@ LIBICAL_ICAL_EXPORT icalerrorstate icalerror_supress(const char *error); * * Calling the function changes the ::icalerrorstate of the given error. * - * ### Usage + * @par Usage * ```c * // suppress internal errors * icalerror_supress("INTERNAL"); diff --git a/src/libical/icalmemory.h b/src/libical/icalmemory.h index 7eb7e010..a57a5c74 100644 --- a/src/libical/icalmemory.h +++ b/src/libical/icalmemory.h @@ -50,7 +50,7 @@ * @return A pointer to the newly created buffer on the ring * * Creates a temporary buffer on the ring. Regardless of what @a size you - * specify, the buffer will always be at least ::MIN_BUFFER_SIZE big, and it + * specify, the buffer will always be at least MIN_BUFFER_SIZE big, and it * will be zeroed out. * * @par Error handling @@ -62,7 +62,7 @@ * caller and the returned memory will be automatically reclaimed as more items * are added to the ring buffer. * - * ### Usage + * @par Usage * ```c * char *str = icalmemory_tmp_buffer(256); * strcpy(str, "some data"); @@ -88,7 +88,7 @@ LIBICAL_ICAL_EXPORT void *icalmemory_tmp_buffer(size_t size); * caller, and it will be automatically reclaimed as more items are added to the * buffer. * - * ### Usage + * @par Usage * ```c * const char *str = "Example string"; * char *tmp_copy = icalmemory_tmp_copy(str); @@ -101,7 +101,7 @@ LIBICAL_ICAL_EXPORT char *icalmemory_tmp_copy(const char *str); * @param buf The externally allocated buffer to add to the ring * * Adds an externally allocated buffer to the ring. This ensures that libical - * will `free()` the buffer automatically, either after ::BUFFER_RING_SIZE other + * will `free()` the buffer automatically, either after BUFFER_RING_SIZE other * buffers have been created or added, or after ::icalmemory_free_ring() has * been called. * @@ -113,7 +113,7 @@ LIBICAL_ICAL_EXPORT char *icalmemory_tmp_copy(const char *str); * be `free()`d manually anymore, it leads to a double-`free()` when icalmemory * reclaims the memory. * - * ### Usage + * @par Usage * ```c * char *buf = calloc(256, sizeof(char)); * @@ -125,11 +125,11 @@ LIBICAL_ICAL_EXPORT void icalmemory_add_tmp_buffer(void *buf); /** * @brief Frees all memory used in the ring * - * Frees all memory used in the ring. Depending on if ::HAVE_PTHREAD is set or + * Frees all memory used in the ring. Depending on if HAVE_PTHREAD is set or * not, the ring buffer is allocated on a per-thread basis, meaning that if all * rings are to be released, it must be called once in every thread. * - * ### Usage + * @par Usage * ``` c * void *buf = icalmemory_tmp_buffer(256); * @@ -162,7 +162,7 @@ LIBICAL_ICAL_EXPORT void icalmemory_free_ring(void); * This creates a new (non-temporary) buffer of the specified @a size. All * buffers returned by this method are zeroed-out. * - * ### Usage + * @par Usage * ```c * // create buffer * char *buffer = icalmemory_new_buffer(50); @@ -194,7 +194,7 @@ LIBICAL_ICAL_EXPORT void *icalmemory_new_buffer(size_t size); * appropriate icalmemory_free_buffer() method. The old buffer, @a buf, can not * be used anymore after calling this method. * - * ### Usage + * @par Usage * ```c * // create new buffer * char *buffer = icalmemory_new_buffer(10); @@ -249,7 +249,7 @@ LIBICAL_ICAL_EXPORT void icalmemory_free_buffer(void *buf); * size of @a buf and will be changed if @a buf is reallocated. @a pos will * point to the last byte of the new string in @a buf, usually a `'\0'` * - * ### Example + * @par Example * ```c * // creates a new buffer * int buffer_len = 15; @@ -291,7 +291,7 @@ LIBICAL_ICAL_EXPORT void icalmemory_append_string(char **buf, char **pos, size_t * reallocated. @a pos will point to the new terminating `'\0'` character @a * buf. * - * ### Example + * @par Example * ```c * // creates a new buffer * int buffer_len = 15; @@ -328,7 +328,7 @@ LIBICAL_ICAL_EXPORT void icalmemory_append_char(char **buf, char **pos, size_t * * A wrapper around `strdup()`. Partly to trap calls to `strdup()`, partly * because in `-ansi`, `gcc` on Red Hat claims that `strdup()` is undeclared. * - * ### Usage + * @par Usage * ```c * const char *my_str = "LibIcal"; * char *dup = icalmemory_strdup(my_str); diff --git a/src/libical/icalparameter.h b/src/libical/icalparameter.h index 57630a22..494cc529 100644 --- a/src/libical/icalparameter.h +++ b/src/libical/icalparameter.h @@ -33,9 +33,9 @@ /*typedef struct icalparameter_impl icalparameter;*/ /** - * @brief Creates new ::icalparameter object. - * @param kind The kind of ::icalparameter to create. - * @return An ::icalparameter with the given kind. + * @brief Creates new icalparameter object. + * @param kind The kind of icalparameter to create. + * @return An icalparameter with the given kind. * * @par Error handling * If there was an internal error regarding @@ -46,7 +46,7 @@ * Objects created by this method are owned by the caller and * must be released with the icalparameter_free() method. * - * ### Usage + * @par Usage * ```c * // create new parameter * icalparameter *parameter = icalparameter_new(); @@ -62,9 +62,9 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new(icalparameter_kind kind); /** - * @brief Creates new ::icalparameter as a clone of the given one. + * @brief Creates new icalparameter as a clone of the given one. * @param p The existing, non-`NULL` parameter to clone. - * @return An ::icalparameter that is a clone of the given one. + * @return An icalparameter that is a clone of the given one. * * @par Error handling * If @a p is `NULL`, it returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR. @@ -75,7 +75,7 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new(icalparameter_kind kind); * Objects created by this method are owned by the caller and * must be released with the icalparameter_free() method. * - * ### Usage + * @par Usage * ```x * // create an icalparameter * icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR"); @@ -95,9 +95,9 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new(icalparameter_kind kind); LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_clone(icalparameter *p); /** - * @brief Creates new ::icalparameter object from string - * @param value The string from which to create the ::icalparameter, in the form `"PARAMNAME=VALUE"` - * @return An ::icalparameter that corresponds to the given string. + * @brief Creates new icalparameter object from string + * @param value The string from which to create the icalparameter, in the form `"PARAMNAME=VALUE"` + * @return An icalparameter that corresponds to the given string. * * @par Error handling * If there was an internal error copying data, it returns `NULL` and sets @@ -109,7 +109,7 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_clone(icalparameter *p); * Objects created by this method are owned by the caller and * must be released with the icalparameter_free() method. * - * ### Usage + * @par Usage * ```c * icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR"); * @@ -123,10 +123,10 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_clone(icalparameter *p); LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_from_string(const char *value); /** - * @brief Creates new ::icalparameter of a given @a kind with a given @a value - * @param kind The kind of ::icalparameter to create + * @brief Creates new icalparameter of a given @a kind with a given @a value + * @param kind The kind of icalparameter to create * @param value The value of the parameter - * @return An ::icalparameter with the given kind and value. + * @return An icalparameter with the given kind and value. * * @par Error handling * If value is `NULL`, it returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR. @@ -135,7 +135,7 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_from_string(const char *val * Objects created by this method are owned by the caller and * must be released with the icalparameter_free() method. * - * ### Example + * @par Example * ```c * // create new parameter * icalparameter *param; @@ -153,7 +153,7 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_from_value_string(icalparam const char *value); /** - * @brief Frees an ::icalparameter object. + * @brief Frees an icalparameter object. * @param parameter The icalparameter to free * * This method needs to be used on all parameter objects returned @@ -161,7 +161,7 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_from_value_string(icalparam * icalparameter_new_from_string() and icalparameter_new_from_value_string(), * when they are not needed anymore and to be released. * - * ### Usage + * @par Usage * ```c * icalparameter *param = icalparameter_new(); * @@ -176,8 +176,8 @@ LIBICAL_ICAL_EXPORT icalparameter *icalparameter_new_from_value_string(icalparam LIBICAL_ICAL_EXPORT void icalparameter_free(icalparameter *parameter); /** - * @brief Converts ::icalparameter into a string representation - * @param parameter The ::icalparameter to convert + * @brief Converts icalparameter into a string representation + * @param parameter The icalparameter to convert * @return A string representing the parameter according to RFC5445/RFC6868. * @sa icalparameter_as_ical_string_r() * @@ -194,7 +194,7 @@ LIBICAL_ICAL_EXPORT void icalparameter_free(icalparameter *parameter); * the library. A version of this function, which returns strings * that are not owned by libical, is icalparameter_as_ical_string_r(). * - * ### Usage + * @par Usage * ```c * icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR"); * @@ -208,8 +208,8 @@ 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 according to RFC5445/RFC6868. - * @param parameter The ::icalparameter to convert + * @brief Converts icalparameter into an string representation according to RFC5445/RFC6868. + * @param parameter The icalparameter to convert * @return A string representing the parameter * @sa icalparameter_as_ical_string() * @@ -226,7 +226,7 @@ LIBICAL_ICAL_EXPORT char *icalparameter_as_ical_string(icalparameter *parameter) * strings that do not need to be freed manually is * icalparameter_as_ical_string(). * - * ### Usage + * @par Usage * ```c * icalparameter *param = icalparameter_new_from_string("ROLE=CHAIR"); * @@ -293,19 +293,19 @@ LIBICAL_ICAL_EXPORT int icalparameter_isa_parameter(void *param); /** * @brief Sets the X-name of @a param to @a v - * @param param The ::icalparameter to change + * @param param The icalparameter to change * @param v The X-name to set @a param to * @sa icalparameter_get_xname() * * @par Error handling - * If either @a param or @a v are `NULL`, it sets ::icalerrno to ::ICAL_BARARG_ERROR. + * If either @a param or @a v are `NULL`, it sets ::icalerrno to ICAL_BARARG_ERROR. * If there is an error acquiring memory, it sets `errno` to `ENOMEM`. * * @par Ownership * The passed string @a v stays in the ownership of the caller - libical * creates a copy of it. * - * ### Usage + * @par Usage * ```c * // creates new parameter * icalparameter *param = icalparameter_new(); @@ -323,19 +323,19 @@ LIBICAL_ICAL_EXPORT void icalparameter_set_xname(icalparameter *param, const cha /** * @brief Returns the X-name of @a param - * @param param The ::icalparameter whose X-name is to be returned + * @param param The icalparameter whose X-name is to be returned * @return A string representing the X-name of @a param * @sa icalparameter_set_xname() * * @par Error handling * Returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR when a `NULL` - * is passed instead of an ::icalparameter. + * is passed instead of an icalparameter. * * @par Ownership * The string that is returned stays owned by libical and must not * be freed by the caller. * - * ### Usage + * @par Usage * ```c * // creates new parameter * icalparameter *param = icalparameter_new(); @@ -353,19 +353,19 @@ LIBICAL_ICAL_EXPORT const char *icalparameter_get_xname(icalparameter *param); /** * @brief Sets the X-value of @a param to @a v - * @param param The ::icalparameter to change + * @param param The icalparameter to change * @param v The X-value to set @a param to * @sa icalparameter_get_xvalue() * * @par Error handling - * If either @a param or @a v are `NULL`, it sets ::icalerrno to ::ICAL_BARARG_ERROR. + * If either @a param or @a v are `NULL`, it sets ::icalerrno to ICAL_BARARG_ERROR. * If there is an error acquiring memory, it sets `errno` to `ENOMEM`. * * @par Ownership * The passed string @a v stays in the ownership of the caller - libical * creates a copy of it. * - * ### Usage + * @par Usage * ```c * // create new parameter * icalparameter *param = icalparameter_new_from_string("X-TEST=FAIL"); @@ -384,19 +384,19 @@ LIBICAL_ICAL_EXPORT void icalparameter_set_xvalue(icalparameter *param, const ch /** * @brief Returns the X-value of @a param - * @param param The ::icalparameter whose X-value is to be returned + * @param param The icalparameter whose X-value is to be returned * @return A string representing the X-value of @a param * @sa icalparameter_set_xvalue() * * @par Error handling * Returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR when a `NULL` - * is passed instead of an ::icalparameter. + * is passed instead of an icalparameter. * * @par Ownership * The string that is returned stays owned by libical and must not * be freed by the caller. * - * ### Usage + * @par Usage * ```c * // create new parameter * icalparameter *param = icalparameter_new_from_string("X-TEST=FAIL"); @@ -422,14 +422,14 @@ LIBICAL_ICAL_EXPORT const char *icalparameter_get_xvalue(icalparameter *param); * @sa icalparameter_get_iana_name() * * @par Error handling - * If either @a param or @a v are `NULL`, it sets ::icalerrno to ::ICAL_BARARG_ERROR. + * If either @a param or @a v are `NULL`, it sets :calerrno to ICAL_BARARG_ERROR. * If there is an error acquiring memory, it sets `errno` to `ENOMEM`. * * @par Ownership * The passed string @a v stays in the ownership of the caller - libical * creates a copy of it. * - * ### Usage + * @par Usage * ```c * // creates new parameter * icalparameter *param = icalparameter_new(); @@ -447,19 +447,19 @@ LIBICAL_ICAL_EXPORT void icalparameter_set_iana_name(icalparameter *param, const /** * @brief Returns the IANA name of @a param - * @param param The ::icalparameter whose IANA name is to be returned + * @param param The icalparameter whose IANA name is to be returned * @return A string representing the IANA name of @a param * @sa icalparameter_set_iana_name() * * @par Error handling * Returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR when a `NULL` - * is passed instead of an ::icalparameter. + * is passed instead of an icalparameter. * * @par Ownership * The string that is returned stays owned by libical and must not * be freed by the caller. * - * ### Usage + * @par Usage * ```c * // creates new parameter * icalparameter *param = icalparameter_new(); @@ -477,19 +477,19 @@ LIBICAL_ICAL_EXPORT const char *icalparameter_get_iana_name(icalparameter *param /** * @brief Sets the IANA value of @a param to @a v - * @param param The ::icalparameter to change + * @param param The icalparameter to change * @param v The IANA value to set @a param to * @sa icalparameter_get_iana_value() * * @par Error handling - * If either @a param or @a v are `NULL`, it sets ::icalerrno to ::ICAL_BARARG_ERROR. + * If either @a param or @a v are `NULL`, it sets ::icalerrno to ICAL_BARARG_ERROR. * If there is an error acquiring memory, it sets `errno` to `ENOMEM`. * * @par Ownership * The passed string @a v stays in the ownership of the caller - libical * creates a copy of it. * - * ### Usage + * @par Usage * ```c * // create new parameter * icalparameter *param = icalparameter_new_from_string("ROLE=ATTENDEE"); @@ -508,19 +508,19 @@ LIBICAL_ICAL_EXPORT void icalparameter_set_iana_value(icalparameter *param, cons /** * @brief Returns the IANA value of @a param - * @param param The ::icalparameter whose value is to be returned + * @param param The icalparameter whose value is to be returned * @return A string representing the value of @a param * @sa icalparameter_set_iana_value() * * @par Error handling * Returns `NULL` and sets ::icalerrno to ::ICAL_BADARG_ERROR when a `NULL` - * is passed instead of an ::icalparameter. + * is passed instead of an icalparameter. * * @par Ownership * The string that is returned stays owned by libical and must not * be freed by the caller. * - * ### Usage + * @par Usage * ```c * // create new parameter * icalparameter *param = icalparameter_new_from_string("ROLE=ATTENDEE"); @@ -548,9 +548,9 @@ LIBICAL_ICAL_EXPORT const char *icalparameter_get_iana_value(icalparameter *para * ::icalerrno to ::ICAL_BADARG_ERROR. * * @par Ownership - * Does not take ownership of either ::icalparameter. + * Does not take ownership of either icalparameter. * - * ### Example + * @par Example * ```c * // create two parameters * icalparameter *param1 = icalparameter_new_from_string("ROLE=CHAIR"); @@ -569,18 +569,18 @@ LIBICAL_ICAL_EXPORT int icalparameter_has_same_name(icalparameter *param1, icalp /* Convert enumerations */ /** - * @brief Returns a string representing the given ::icalparameter_kind + * @brief Returns a string representing the given icalparameter_kind * @param kind The icalparameter_kind * @return A string representing @a kind * * @par Error handling - * When passed a non-existing ::icalparameter_kind, it returns `NULL`. + * When passed a non-existing icalparameter_kind, it returns `NULL`. * * @par Ownership * The string that is returned by this function is owned by libical and * must not be freed by the caller. * - * ### Usage + * @par Usage * ```c * assert(0 == strcmp(icalparameter_kind_to_string(ICAL_ROLE_PARAMETER), "ROLE")); * assert(0 == strcmp(icalparameter_kind_to_string(ICAL_EMAIL_PARAMETER), "EMAIL)); @@ -590,20 +590,20 @@ LIBICAL_ICAL_EXPORT int icalparameter_has_same_name(icalparameter *param1, icalp LIBICAL_ICAL_EXPORT const char *icalparameter_kind_to_string(icalparameter_kind kind); /** - * @brief Returns the ::icalparameter_kind for a given string + * @brief Returns the icalparameter_kind for a given string * @param string A string describing an icalparameter_kind * @return An icalparameter_kind * * @par Error handling - * Returns ::ICAL_NO_PARAMETER if @a string is `NULL`. + * Returns ICAL_NO_PARAMETER if @a string is `NULL`. * If it can't find the parameter, depending on * the ical_get_unknown_token_handling_setting(), it returns either - * ::ICAL_NO_PARAMETER or ::ICAL_IANA_PARAMETER. + * ICAL_NO_PARAMETER or ICAL_IANA_PARAMETER. * * @par Ownership * Does not take ownership of @a string. * - * ### Usage + * @par Usage * ```c * assert(icalparameter_string_to_kind("ROLE") == ICAL_ROLE_PARAMETER); * assert(icalparameter_string_to_kind("EMAIL") == ICAL_EMAIL_PARAMETER); @@ -613,11 +613,11 @@ LIBICAL_ICAL_EXPORT const char *icalparameter_kind_to_string(icalparameter_kind LIBICAL_ICAL_EXPORT icalparameter_kind icalparameter_string_to_kind(const char *string); /** - * @brief Checks the validity of a ::icalparameter_kind + * @brief Checks the validity of a icalparameter_kind * @param kind The icalparameter_kind * @return 1 if @a kind is valid, 0 otherwise * - * ### Usage + * @par Usage * ```c * assert(icalparameter_kind_is_valid(ICAL_ROLE_PARAMETER)); * ``` diff --git a/src/libical/icalparser.h b/src/libical/icalparser.h index 765f7730..850bf33a 100644 --- a/src/libical/icalparser.h +++ b/src/libical/icalparser.h @@ -31,7 +31,7 @@ * This file provides methods to parse iCalendar-formatted data * into the structures provided by this library. * - * ### Usage + * @par Usage * Create a new parser via icalparser_new_parser(), then add lines one at * a time with icalparser_add_line(). icalparser_add_line() will return * non-zero when it has finished with a component. @@ -73,18 +73,18 @@ typedef enum icalparser_state typedef char *(*icalparser_line_gen_func) (char *s, size_t size, void *d); /** - * @brief Creates a new ::icalparser. - * @return An ::icalparser object + * @brief Creates a new icalparser. + * @return An icalparser object * * @par Error handling * On error, it returns `NULL` and sets ::icalerrno to * ::ICAL_NEWFAILED_ERROR. * * @par Ownership - * All ::icalparser objects created with this function need to be + * All icalparser objects created with this function need to be * freed using the icalparser_free() function. * - * ### Usage + * @par Usage * ```c * // create new parser * icalparser *parser = icalparser_new(); @@ -98,7 +98,7 @@ typedef char *(*icalparser_line_gen_func) (char *s, size_t size, void *d); LIBICAL_ICAL_EXPORT icalparser *icalparser_new(void); /** - * @brief Adds a single line to be parsed by the ::icalparser. + * @brief Adds a single line to be parsed by the icalparser. * @param parser The parser to use * @param str A string representing a single line of RFC5545-formatted iCalendar data * @return When this was the last line of the component to be parsed, @@ -112,15 +112,15 @@ LIBICAL_ICAL_EXPORT icalparser *icalparser_new(void); * - If @a line is `NULL`, it returns `NULL` and sets the @a parser's ::icalparser_state to * ::ICALPARSER_ERROR. * - For errors during parsing, the functions can set the ::icalparser_state to - * ::ICALPARSER_ERROR and/or return components of the type ::ICAL_XLICINVALID_COMPONENT, - * or components with properties of the type ::ICAL_XLICERROR_PROPERTY. + * ::ICALPARSER_ERROR and/or return components of the type ICAL_XLICINVALID_COMPONENT, + * or components with properties of the type ICAL_XLICERROR_PROPERTY. * * @par Ownership * Ownership of the @a str is transferred to libical upon calling this - * method. The returned ::icalcomponent is owned by the caller and needs + * method. The returned icalcomponent is owned by the caller and needs * to be `free()`d with the appropriate method after it's no longer needed. * - * ### Example + * @par Example * ```c * char* read_stream(char *s, size_t size, void *d) * { @@ -159,9 +159,9 @@ LIBICAL_ICAL_EXPORT icalparser *icalparser_new(void); LIBICAL_ICAL_EXPORT icalcomponent *icalparser_add_line(icalparser *parser, char *str); /** - * @brief Cleans out an ::icalparser and returns whatever it has parsed so far. - * @param parser The ::icalparser to clean - * @return The parsed ::icalcomponent + * @brief Cleans out an icalparser and returns whatever it has parsed so far. + * @param parser The icalparser to clean + * @return The parsed icalcomponent * * @par Error handling * If @a parser is `NULL`, it returns `NULL` and sets ::icalerrno to @@ -169,7 +169,7 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalparser_add_line(icalparser *parser, char * property into the affected components. * * @par Ownership - * The returned ::icalcomponent is property of the caller and needs to be + * The returned icalcomponent is property of the caller and needs to be * free'd with icalcomponent_free() after use. * * This will parse components even if it hasn't encountered a proper @@ -184,7 +184,7 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalparser_clean(icalparser *parser); * @param parser The (valid, non-`NULL`) parser object * @return The current state of the icalparser, as an ::icalparser_state * - * ### Example + * @par Example * ```c * icalparser *parser = icalparser_new(); * @@ -202,10 +202,10 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalparser_clean(icalparser *parser); LIBICAL_ICAL_EXPORT icalparser_state icalparser_get_state(icalparser *parser); /** - * @brief Frees an ::icalparser object. - * @param parser The ::icalparser to be freed. + * @brief Frees an icalparser object. + * @param parser The icalparser to be freed. * - * ### Example + * @par Example * ```c * icalparser *parser = icalparser_new(); * @@ -232,14 +232,14 @@ LIBICAL_ICAL_EXPORT void icalparser_free(icalparser *parser); * - If data read by @a line_gen_func is `NULL`, it returns `NULL` * and sets the @a parser's ::icalparser_state to ::ICALPARSER_ERROR. * - For errors during parsing, the functions can set the ::icalparser_state to - * ::ICALPARSER_ERROR and/or return components of the type ::ICAL_XLICINVALID_COMPONENT, - * or components with properties of the type ::ICAL_XLICERROR_PROPERTY. + * ::ICALPARSER_ERROR and/or return components of the type ICAL_XLICINVALID_COMPONENT, + * or components with properties of the type ICAL_XLICERROR_PROPERTY. * * @par Ownership - * The returned ::icalcomponent is owned by the caller of the function, and + * The returned icalcomponent is owned by the caller of the function, and * needs to be `free()`d with the appropriate method when no longer needed. * - * ### Example + * @par Example * ```c * char* read_stream(char *s, size_t size, void *d) * { @@ -284,18 +284,18 @@ LIBICAL_ICAL_EXPORT icalcomponent *icalparser_parse(icalparser *parser, LIBICAL_ICAL_EXPORT void icalparser_set_gen_data(icalparser *parser, void *data); /** - * @brief Parses a string and returns the parsed ::icalcomponent. + * @brief Parses a string and returns the parsed icalcomponent. * @param str The iCal formatted data to be parsed - * @return An ::icalcomponent representing the iCalendar + * @return An icalcomponent representing the iCalendar * * @par Error handling * On error, returns `NULL` and sets ::icalerrno * * @par Ownership - * The returned ::icalcomponent is owned by the caller of the function, and + * The returned icalcomponent is owned by the caller of the function, and * needs to be free'd with the appropriate functions after use. * - * ### Example + * @par Example * ```c * char *ical_string; * diff --git a/src/libical/icalperiod.h b/src/libical/icalperiod.h index fb8e3140..4b1034e9 100644 --- a/src/libical/icalperiod.h +++ b/src/libical/icalperiod.h @@ -57,7 +57,7 @@ struct icalperiodtype * If @a str is not properly formatted, it sets ::icalerrno to * ::ICAL_MALFORMEDDATA_ERROR and returns icalperiodtype_null_period(). * - * ### Data format + * @par Data format * There are two ways to specify a duration; either a start time * and an end time can be specified, or a start time and a duration. * The format for there is as such: @@ -68,7 +68,7 @@ struct icalperiodtype * icaltime_from_string(), and the format for the duration * is the same as that used by icaldurationtype_from_string(). * - * ### Usage + * @par Usage * ```c * // create icalperiodtype * const char *period_string = "20170606T090000/20170607T090000"; @@ -94,7 +94,7 @@ LIBICAL_ICAL_EXPORT struct icalperiodtype icalperiodtype_from_string(const char * The string returned by this method is owned by libical and must not be * `free()` by the caller. * - * ### Example + * @par Example * ```c * // create icalperiodtype * const char *period_string = "20170606T090000/20170607T090000"; @@ -120,7 +120,7 @@ LIBICAL_ICAL_EXPORT const char *icalperiodtype_as_ical_string(struct icalperiodt * The string returned by this method is owned by the caller and must be * released with the appropriate function after use. * - * ### Example + * @par Example * ```c * // create icalperiodtype * const char *period_string = "20170606T090000/20170607T090000"; @@ -139,7 +139,7 @@ LIBICAL_ICAL_EXPORT char *icalperiodtype_as_ical_string_r(struct icalperiodtype * @return An ::icalperiodtype representing a null period * @sa icalperiodtype_is_null_period() * - * ### Usage + * @par Usage * ```c * // creates null period * struct icalperiodtype period = icalperiodtype_null_period(); @@ -158,7 +158,7 @@ LIBICAL_ICAL_EXPORT struct icalperiodtype icalperiodtype_null_period(void); * @return 1 if @a p is a null period, 0 otherwise * @sa icalperiodtype_null_period() * - * ### Usage + * @par Usage * ```c * // creates null period * struct icalperiodtype period = icalperiodtype_null_period(); @@ -174,7 +174,7 @@ LIBICAL_ICAL_EXPORT int icalperiodtype_is_null_period(struct icalperiodtype p); * @param p The time period to check * @return 1 if @a p is a valid period, 0 otherwise * - * ### Usage + * @par Usage * ```c * // creates null period * struct icalperiodtype period = icalperiodtype_null_period(); diff --git a/src/libical/icalproperty.h b/src/libical/icalproperty.h index f4411cf6..e326eb24 100644 --- a/src/libical/icalproperty.h +++ b/src/libical/icalproperty.h @@ -90,7 +90,7 @@ LIBICAL_ICAL_EXPORT void icalproperty_remove_parameter_by_name(icalproperty *pro /** @brief Removes the specified parameter reference from the property. * * @param prop A valid icalproperty. - * @param parameter A reference to a specific icalparameter. + * @param param A reference to a specific icalparameter. * * This function removes the specified parameter reference from the * property. diff --git a/src/libical/icalrestriction.h b/src/libical/icalrestriction.h index 38751efc..752cf457 100644 --- a/src/libical/icalrestriction.h +++ b/src/libical/icalrestriction.h @@ -26,7 +26,7 @@ /** * @file icalrestriction.h - * @brief Functions to check if an ::icalcomponent meets the restrictions + * @brief Functions to check if an icalcomponent meets the restrictions * imposed by the standard. */ @@ -76,7 +76,7 @@ typedef enum icalrestriction_kind * @param count The amount present that is to be checked against the restriction * @return 1 if the restriction is met, 0 if not * - * ### Example + * @par Example * ```c * assert(icalrestriction_compare(ICALRESTRICTION_ONEPLUS, 5) == true); * assert(icalrestriction_compare(ICALRESTRICTION_NONE, 3) == false); @@ -94,7 +94,7 @@ LIBICAL_ICAL_EXPORT int icalrestriction_compare(icalrestriction_kind restr, int * Returns 0 and sets ::icalerrno if `NULL` is passed as @a comp, or if the * component is not a `VCALENDAR`. * - * ### Example + * @par Example * ```c * icalcomponent *component = // ... * diff --git a/src/libical/icaltime.h b/src/libical/icaltime.h index 1e28492b..ca69724f 100644 --- a/src/libical/icaltime.h +++ b/src/libical/icaltime.h @@ -352,7 +352,7 @@ LIBICAL_ICAL_EXPORT void icaltime_adjust(struct icaltimetype *tt, * to do arithmetic on times without worrying about overflow or * underflow. */ -LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_normalize(const struct icaltimetype t); +LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_normalize(const struct icaltimetype tt); /** @brief Converts time to a given timezone. * @@ -363,7 +363,7 @@ LIBICAL_ICAL_EXPORT struct icaltimetype icaltime_normalize(const struct icaltime * * If it's a floating time, the returned object * represents the same time relative to @p zone. - * For example, if @tt represents 9:30 AM floating and @p zone + * For example, if @p tt represents 9:30 AM floating and @p zone * is the GMT timezone, the returned object will represent 9:30 AM GMT. * * Otherwise, the time will be converted to @p zone, and its timezone diff --git a/src/libicalss/icalspanlist.c b/src/libicalss/icalspanlist.c index b74047ff..e697d948 100644 --- a/src/libicalss/icalspanlist.c +++ b/src/libicalss/icalspanlist.c @@ -189,22 +189,22 @@ icalspanlist *icalspanlist_new(icalset *set, struct icaltimetype start, struct i return sl; } -void icalspanlist_free(icalspanlist *s) +void icalspanlist_free(icalspanlist *sl) { struct icaltime_span *span; - if (s == NULL) + if (sl == NULL) return; - while ((span = pvl_pop(s->spans)) != 0) { + while ((span = pvl_pop(sl->spans)) != 0) { free(span); } - pvl_free(s->spans); + pvl_free(sl->spans); - s->spans = 0; + sl->spans = 0; - free(s); + free(sl); } void icalspanlist_dump(icalspanlist *sl) diff --git a/src/libicalss/icalspanlist.h b/src/libicalss/icalspanlist.h index c5b44cd1..fb817ef7 100644 --- a/src/libicalss/icalspanlist.h +++ b/src/libicalss/icalspanlist.h @@ -44,11 +44,11 @@ LIBICAL_ICALSS_EXPORT icalspanlist *icalspanlist_new(icalset *set, struct icaltimetype end); /** @brief Destructor. - * @param s A valid icalspanlist + * @param sl A valid icalspanlist * * Frees the memory associated with the spanlist. */ -LIBICAL_ICALSS_EXPORT void icalspanlist_free(icalspanlist *spl); +LIBICAL_ICALSS_EXPORT void icalspanlist_free(icalspanlist *sl); /** @brief Finds the next free time span in a spanlist. * @@ -64,7 +64,7 @@ LIBICAL_ICALSS_EXPORT struct icalperiodtype icalspanlist_next_free_time(icalspan /** @brief (Debug) print out spanlist to STDOUT. * @param sl A valid icalspanlist. */ -LIBICAL_ICALSS_EXPORT void icalspanlist_dump(icalspanlist *s); +LIBICAL_ICALSS_EXPORT void icalspanlist_dump(icalspanlist *sl); /** @brief Returns a VFREEBUSY component for a spanlist. * @@ -87,7 +87,7 @@ LIBICAL_ICALSS_EXPORT icalcomponent *icalspanlist_as_vfreebusy(icalspanlist *sl, /** @brief Returns an hour-by-hour array of free/busy times over a * given period. * - * @param sl A valid icalspanlist + * @param span A valid icalspanlist * @param delta_t The time slice to divide by, in seconds. Default 3600. * * @return A pointer to an array of integers containing the number of |