improve doxgen documentation. fix doxygen warnings

15 files changed, 195 insertions, 195 deletions

diff --git a/doc/Doxyfile.cmake b/doc/Doxyfile.cmake
index 41c166b2..8ecbf3f2 100644
--- a/doc/Doxyfile.cmake
+++ b/doc/Doxyfile.cmake
@@ -106,7 +106,7 @@ EXCLUDE_PATTERNS       = */.svn/* \
 EXAMPLE_PATH           =
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = @CMAKE_SOURCE_DIR@/docs
+IMAGE_PATH             = @CMAKE_SOURCE_DIR@/doc
 INPUT_FILTER           =
 FILTER_PATTERNS        =
 FILTER_SOURCE_FILES    = NO
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