From 6285d214aab6c678248f57f3f61fc3c3420b8fdb Mon Sep 17 00:00:00 2001 From: Laurence Withers Date: Fri, 8 Jan 2010 18:46:34 +0000 Subject: [PATCH] Documentation and annotation updates This commit updates the Doxygen documentation (particularly taking into account a request from Kelly Dunlop for more verbose notice about which members are changed by iso8601_from_*()) and file/function annotation/formatting to current standards. --- src/libiso8601/100_types.h | 46 ++++++++------- src/libiso8601/200_parser.h | 62 ++++++++++++-------- src/libiso8601/400_c_library.h | 66 ++++++++++++++++------ src/libiso8601/400_calc.h | 100 +++++++++++++++++++++++++-------- src/libiso8601/400_leap.h | 99 ++++++++++++++++++++------------ src/libiso8601/400_manip.h | 83 +++++++++++++++++++-------- 6 files changed, 315 insertions(+), 141 deletions(-) diff --git a/src/libiso8601/100_types.h b/src/libiso8601/100_types.h index 77b0a01..fa92a77 100644 --- a/src/libiso8601/100_types.h +++ b/src/libiso8601/100_types.h @@ -1,7 +1,7 @@ /* libiso8601/src/libiso8601/100_types.h * - * (c)2006, Laurence Withers, . - * Released under the GNU GPLv2. See file COPYING or + * (c)2006-2010, Laurence Withers, . + * Released under the GNU GPLv3. See file COPYING or * http://www.gnu.org/copyleft/gpl.html for details. */ @@ -9,19 +9,20 @@ /*! \brief Date/time point. -This structure contains the details to represent a specific instant on the UTC timescale. It uses -Jan 1, year 0000 as the origin (when \a day will be 0). \a sec is the number of seconds elapsed -since start of day, and \a nsec is the number of nanoseconds elapsed since the start of the current -second. +This structure contains the details to represent a specific instant on the UTC +timescale. It uses Jan 1, year 0000 as the origin (when \a day will be 0). \a +sec is the number of seconds elapsed since start of day, and \a nsec is the +number of nanoseconds elapsed since the start of the current second. -We correctly deal with leap seconds by encoding 23:59:60 as having a \a sec field of 86400. +We correctly deal with leap seconds by encoding 23:59:60 as having a \a sec +field of 86400. */ struct iso8601_date { /*! \brief Number of nanoseconds elapsed since start of second. */ int32_t nsec; - /*! \brief Number of days elapsed since Jan 1, year 0000. May be negative. */ + /*! \brief Number of days elapsed since Jan 1, year 0000. May be negative.*/ int32_t day; /*! \brief Number of seconds elapsed since start of day. */ @@ -33,9 +34,10 @@ struct iso8601_date { /*! \brief Date (day portion) precision. \ingroup parser -This enumeration will record how precisely the date was specified, as well as the format in use. It -allows the library to determine the earliest and latest dates that could possibly be represented -with the given input and also allows the output format to match the input format. +This enumeration will record how precisely the date was specified, as well as +the format in use. It allows the library to determine the earliest and latest +dates that could possibly be represented with the given input and also allows +the output format to match the input format. */ enum iso8601_date_prec { @@ -63,9 +65,10 @@ enum iso8601_date_prec { /*! \brief Time precision. \ingroup parser -This enumeration records how precisely the time was specified as well as its format. The fractional -format will record whether it was the hour, minute or second that was specified with a fractional -part, allowing a processed date/time to be presented to the user in the format it was originally +This enumeration records how precisely the time was specified as well as its +format. The fractional format will record whether it was the hour, minute or +second that was specified with a fractional part, allowing a processed +date/time to be presented to the user in the format it was originally encountered. */ @@ -90,10 +93,10 @@ enum iso8601_time_prec { /*! \brief Date/time formatting details. -This structure simply records details related to the formatting (and precision) of a date/time -structure. The structure can be filled out by the parser so that a program's output can match -the format of its input. Alternatively it can be controlled by the program to provide a consistent -output format. +This structure simply records details related to the formatting (and precision) +of a date/time structure. The structure can be filled out by the parser so that +a program's output can match the format of its input. Alternatively it can be +controlled by the program to provide a consistent output format. */ struct iso8601_details { @@ -114,9 +117,10 @@ struct iso8601_details { /*! \brief Short period elapsed time. -This structure contains the details of an elapsed time period, split into seconds and nanoseconds. -None of its components can ever be negative. This is only capable of representing short (compared to -struct iso8601_date's range) periods of up to approximately 136 years. +This structure contains the details of an elapsed time period, split into +seconds and nanoseconds. None of its components can ever be negative. This is +only capable of representing short (compared to struct iso8601_date's range) +periods of up to approximately 136 years. */ struct iso8601_elapsed { diff --git a/src/libiso8601/200_parser.h b/src/libiso8601/200_parser.h index 3aa4e85..ed31849 100644 --- a/src/libiso8601/200_parser.h +++ b/src/libiso8601/200_parser.h @@ -1,7 +1,7 @@ /* libiso8601/src/libiso8601/200_parser.h * - * (c)2006, Laurence Withers, . - * Released under the GNU GPLv2. See file COPYING or + * (c)2006-2010, Laurence Withers, . + * Released under the GNU GPLv3. See file COPYING or * http://www.gnu.org/copyleft/gpl.html for details. */ @@ -9,31 +9,41 @@ /*! \defgroup parser Parsing, printing and validation routines. -These routines are used for parsing an ISO8601 date/time string into the internal structure used -to represent them, and for validating such dates/times. +These routines are used for parsing an ISO8601 date/time string into the +internal structure used to represent them, and for validating such dates/times. */ /*!@{*/ + + /*! \brief Parse ISO8601 date/time. \param str The input string. Whitespace will be stripped. -\param[out] earliest The earliest possible time the string could represent. May be 0. -\param[out] latest The latest possible time the string could represent. May be 0. -\param[out] details Stores details such as the precision to which the time/date were specified. May +\param[out] earliest The earliest possible time the string could represent. May be 0. +\param[out] latest The latest possible time the string could represent. May be + 0. +\param[out] details Stores details such as the precision to which the time/date + were specified. May be 0. \retval -1 on error. \retval 0 on success. -Parses a string containing the ISO8601 date/time. Deals with any format of date, optionally storing -the details in \a details. The time may be partial, in which case this function returns the earliest -and latest times that could possibly be represented by the string. +Parses a string containing the ISO8601 date/time. Deals with any format of +date, optionally storing the details in \a details. The time may be partial, in +which case this function returns the earliest and latest times that could +possibly be represented by the string. -Note that this function will accept leap seconds (23:59:60) on days on which they occurred. +Note that this function will accept leap seconds (23:59:60) on days on which +they occurred. */ -int iso8601_parse(const char* str, struct iso8601_date* earliest, struct iso8601_date* latest, - struct iso8601_details* details); +int iso8601_parse(const char* str, struct iso8601_date* earliest, + struct iso8601_date* latest, struct iso8601_details* details) +#ifndef DOXYGEN + __attribute__((nonnull(1),warn_unused_result)) +#endif +; @@ -45,12 +55,17 @@ int iso8601_parse(const char* str, struct iso8601_date* earliest, struct iso8601 \param details Formatting details (may be 0). \returns Pointer to buffer (\a str). -Formats and prints an ISO8601 date, optionally using the details in \a details. Will always return -a null-terminated result, even if that means truncating the output to fit the buffer. +Formats and prints an ISO8601 date, optionally using the details in \a details. +Will always return a null-terminated result, even if that means truncating the +output to fit the buffer. */ char* iso8601_print(char* str, int amt, const struct iso8601_date* date, - const struct iso8601_details* details); + const struct iso8601_details* details) +#ifndef DOXYGEN + __attribute__((nonnull(1,3))) +#endif +; @@ -60,18 +75,21 @@ char* iso8601_print(char* str, int amt, const struct iso8601_date* date, \retval -1 if not valid. \retval 0 if valid. -Checks the details of \a date to ensure that they are sensible. This involves checking that \a sec -is in the range 0 to 86399 (or 86400 if there is a leap second), and that \a nsec is in the range 0 -to 999999999. +Checks the details of \a date to ensure that they are sensible. This involves +checking that \a sec is in the range 0 to 86399 (or 86400 if there is a leap +second), and that \a nsec is in the range 0 to 999999999. */ -int iso8601_invalid(const struct iso8601_date* date); +int iso8601_invalid(const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; /*!@}*/ - /* options for text editors kate: replace-trailing-space-save true; space-indent true; tab-width 4; -vim: expandtab:ts=4:sw=4 +vim: expandtab:ts=4:sw=4:syntax=ch.doxygen */ diff --git a/src/libiso8601/400_c_library.h b/src/libiso8601/400_c_library.h index c5e6b59..1a75cd0 100644 --- a/src/libiso8601/400_c_library.h +++ b/src/libiso8601/400_c_library.h @@ -1,7 +1,7 @@ /* libiso8601/src/libiso8601/400_c_library.h * - * (c)2006, Laurence Withers, . - * Released under the GNU GPLv2. See file COPYING or + * (c)2006-2010, Laurence Withers, . + * Released under the GNU GPLv3. See file COPYING or * http://www.gnu.org/copyleft/gpl.html for details. */ @@ -9,7 +9,8 @@ /*! \defgroup c_library C library integration. -These functions enable integration with the C library (system call wrappers and conversion). +These functions enable integration with the C library (system call wrappers and +conversion). */ /*!@{*/ @@ -21,8 +22,8 @@ These functions enable integration with the C library (system call wrappers and \param[out] date Current date/time (may be 0), in UTC. \param[out] details Details (may be 0), including timezone. -Retrieves the current time from the system clock, storing it into \a date and \a details (both -parameters optional). +Retrieves the current time from the system clock, storing it into \a date and +\a details (both parameters optional). */ void iso8601_now(struct iso8601_date* date, struct iso8601_details* details); @@ -35,32 +36,65 @@ void iso8601_now(struct iso8601_date* date, struct iso8601_details* details); \retval 0 on success. \retval -1 on error (and see \a errno). -Attempts to set the system clock using \c clock_settime(), falling back to \c settimeofday(). The -user will need the \c CAP_SYS_TIME capability to set the clock, otherwise \a errno will be set to -\c EPERM. +Attempts to set the system clock using \c clock_settime(), falling back to \c +settimeofday(). The user will need the \c CAP_SYS_TIME capability to set the +clock, otherwise \a errno will be set to \c EPERM. */ -int iso8601_set_sysclock(const struct iso8601_date* date); +int iso8601_set_sysclock(const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; /*! \brief Convert from a struct timespec. */ -void iso8601_from_ts(struct iso8601_date* date, const struct timespec* ts); +void iso8601_from_ts(struct iso8601_date* date, const struct timespec* ts) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; + /*! \brief Convert to a struct timespec. */ -void iso8601_to_ts(struct timespec* ts, const struct iso8601_date* date); +void iso8601_to_ts(struct timespec* ts, const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; + /*! \brief Convert from a struct timeval. */ -void iso8601_from_tv(struct iso8601_date* date, const struct timeval* tv); +void iso8601_from_tv(struct iso8601_date* date, const struct timeval* tv) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; + /*! \brief Convert to a struct timeval. */ -void iso8601_to_tv(struct timeval* tv, const struct iso8601_date* date); +void iso8601_to_tv(struct timeval* tv, const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; + /*! \brief Convert from a time_t. */ -void iso8601_from_time_t(struct iso8601_date* date, const time_t* t); +void iso8601_from_time_t(struct iso8601_date* date, const time_t* t) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; + /*! \brief Convert to a time_t. */ -void iso8601_to_time_t(time_t* t, const struct iso8601_date* date); +void iso8601_to_time_t(time_t* t, const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; /*!@}*/ /* options for text editors kate: replace-trailing-space-save true; space-indent true; tab-width 4; -vim: expandtab:ts=4:sw=4 +vim: expandtab:ts=4:sw=4:syntax=ch.doxygen */ diff --git a/src/libiso8601/400_calc.h b/src/libiso8601/400_calc.h index 0145a35..9570d8d 100644 --- a/src/libiso8601/400_calc.h +++ b/src/libiso8601/400_calc.h @@ -1,7 +1,7 @@ /* libiso8601/src/libiso8601/400_calc.h * - * (c)2006, Laurence Withers, . - * Released under the GNU GPLv2. See file COPYING or + * (c)2006-2010, Laurence Withers, . + * Released under the GNU GPLv3. See file COPYING or * http://www.gnu.org/copyleft/gpl.html for details. */ @@ -9,8 +9,8 @@ /*! \defgroup calc Conversion and calculation routines. -This set of functions is useful for converting dates and times into formats understood by humans, -and vice versa. +This set of functions is useful for converting dates and times into formats +understood by humans, and vice versa. */ /*!@{*/ @@ -26,7 +26,11 @@ and vice versa. Returns non-0 if \a year is a leap year. */ -int iso8601_isleap(int year); +int iso8601_isleap(int year) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -38,7 +42,12 @@ int iso8601_isleap(int year); \param date Date to convert. */ -void iso8601_to_cal(int* year, int* month, int* day, const struct iso8601_date* date); +void iso8601_to_cal(int* year, int* month, int* day, + const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -51,11 +60,18 @@ void iso8601_to_cal(int* year, int* month, int* day, const struct iso8601_date* \retval 0 on success. \retval -1 on error (and see \a errno). -Converts the date specified in \a year, \a month and \a day into \a date. Does not touch the \a sec -or \a nsec time members of \a date. +Converts the date specified in \a year, \a month and \a day into \a date. + +\note Does not touch the \a sec or \a nsec time members of \a date. This means + they will be unchanged after a call to this function. If this will lead to + unexpected results, initialise the structure to 0 first. */ -int iso8601_from_cal(struct iso8601_date* date, int year, int month, int day); +int iso8601_from_cal(struct iso8601_date* date, int year, int month, int day) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -66,7 +82,11 @@ int iso8601_from_cal(struct iso8601_date* date, int year, int month, int day); \param date Date to convert. */ -void iso8601_to_ord(int* year, int* oday, const struct iso8601_date* date); +void iso8601_to_ord(int* year, int* oday, const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -78,11 +98,18 @@ void iso8601_to_ord(int* year, int* oday, const struct iso8601_date* date); \retval 0 on success. \retval -1 on error (and see \a errno). -Converts the date specified into \a year and \a oday into \a date. Does not touch the \a sec or -\a nsec time members of \a date. +Converts the date specified into \a year and \a oday into \a date. + +\note Does not touch the \a sec or \a nsec time members of \a date. This means + they will be unchanged after a call to this functoin. If this will lead to + unexpected results, initialise the structure to 0 first. */ -int iso8601_from_ord(struct iso8601_date* date, int year, int oday); +int iso8601_from_ord(struct iso8601_date* date, int year, int oday) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -94,7 +121,12 @@ int iso8601_from_ord(struct iso8601_date* date, int year, int oday); \param date Date to convert. */ -void iso8601_to_week(int* year, int* week, int* wday, const struct iso8601_date* date); +void iso8601_to_week(int* year, int* week, int* wday, + const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -107,8 +139,18 @@ void iso8601_to_week(int* year, int* week, int* wday, const struct iso8601_date* \retval 0 on success. \retval -1 on error (and see \a errno). +Converts the date specified into \a year, \a week and \a wday into \a date. + +\note Does not touch the \a sec or \a nsec time members of \a date. This means + they will be unchanged after a call to this functoin. If this will lead to + unexpected results, initialise the structure to 0 first. + */ -int iso8601_from_week(struct iso8601_date* date, int year, int week, int wday); +int iso8601_from_week(struct iso8601_date* date, int year, int week, int wday) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -119,11 +161,16 @@ int iso8601_from_week(struct iso8601_date* date, int year, int week, int wday); \param[out] sec Output second. \param date Date/time to convert. -Converts the time stored in \a date into wall clock format, storing the result in \a hour, \a min -and \a sec. +Converts the time stored in \a date into wall clock format, storing the result +in \a hour, \a min and \a sec. */ -void iso8601_to_clocktime(int* hour, int* min, int* sec, const struct iso8601_date* date); +void iso8601_to_clocktime(int* hour, int* min, int* sec, + const struct iso8601_date* date) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; @@ -136,16 +183,25 @@ void iso8601_to_clocktime(int* hour, int* min, int* sec, const struct iso8601_da \retval 0 on success. \retval -1 on error (and see \a errno). -Converts the time as specified by \a hour, \a min and \a sec, storing the result in \a date. Does -not touch the \a day (date) member of \a date. +Converts the time as specified by \a hour, \a min and \a sec, storing the +result in \a date. + +\note Does not touch the \a day (date) member of \a date. This means it will be + unchanged after a call to this function. If this will lead to unexpected + results, initialise the structure to 0 first. */ -int iso8601_from_clocktime(struct iso8601_date* date, int hour, int min, int sec); +int iso8601_from_clocktime(struct iso8601_date* date, int hour, int min, + int sec) +#ifndef DOXYGEN + __attribute__((nonnull)) +#endif +; /*!@}*/ /* options for text editors kate: replace-trailing-space-save true; space-indent true; tab-width 4; -vim: expandtab:ts=4:sw=4 +vim: expandtab:ts=4:sw=4:syntax=ch.doxygen */ diff --git a/src/libiso8601/400_leap.h b/src/libiso8601/400_leap.h index e090b80..2797464 100644 --- a/src/libiso8601/400_leap.h +++ b/src/libiso8601/400_leap.h @@ -1,7 +1,7 @@ /* libiso8601/src/libiso8601/400_leap.h * - * (c)2006, Laurence Withers, . - * Released under the GNU GPLv2. See file COPYING or + * (c)2006-2010, Laurence Withers, . + * Released under the GNU GPLv3. See file COPYING or * http://www.gnu.org/copyleft/gpl.html for details. */ @@ -9,20 +9,23 @@ /*! \defgroup leap Leap second support. -A set of functions for explicitly dealing with leap seconds. All library functions are implicitly -leap second aware, but there are occasions when leap seconds must be dealt with explicitly. These -functions permit this. +A set of functions for explicitly dealing with leap seconds. All library +functions are implicitly leap second aware, but there are occasions when leap +seconds must be dealt with explicitly. These functions permit this. -Internally, leap seconds are represented as a table of day numbers; each day number present in the -table means that the corresponding day has 86401 seconds (a leap second). +Internally, leap seconds are represented as a table of day numbers; each day +number present in the table means that the corresponding day has 86401 seconds +(a leap second). -\note The library does not (yet) have support for negative leap seconds. This support will be added - should a day with a negative leap second ever come. This will need to addressed in the API as - the current API does not support loading a table of negative leap seconds. +\note The library does not (yet) have support for negative leap seconds. This + support will be added should a day with a negative leap second ever come. + This will need to addressed in the API as the current API does not support + loading a table of negative leap seconds. -It is possible to create a disk file containing an updated table and to load that file using -\ref iso8601_leap_table_load (or to explicitly use an existing in-memory table with -\ref iso8601_leap_table_set). The format of the on-disk file is: +It is possible to create a disk file containing an updated table and to load +that file using \ref iso8601_leap_table_load (or to explicitly use an existing +in-memory table with \ref iso8601_leap_table_set). The format of the on-disk +file is: 
# integers are stored big-endian
 [8*char] signature, "/O9PdPZI"
@@ -43,14 +46,19 @@ It is possible to create a disk file containing an updated table and to load tha
 \retval 86400 day with no leap second.
 \retval 86401 day with one leap second.
 
-Returns the duration of a day \a date, in seconds. This function takes leap seconds into account and
-may be used to determine if a day contains a leap second or not.
+Returns the duration of a day \a date, in seconds. This function takes leap
+seconds into account and may be used to determine if a day contains a leap
+second or not.
 
-\note There have not yet been any days requiring a negative leap second, so at present 86399 will
-    never be returned.
+\note There have not yet been any days requiring a negative leap second, so at
+    present 86399 will never be returned.
 
 */
-int iso8601_seconds_leap(const struct iso8601_date* date);
+int iso8601_seconds_leap(const struct iso8601_date* date)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -60,13 +68,19 @@ int iso8601_seconds_leap(const struct iso8601_date* date);
 \param end The end date.
 \returns Number of leap seconds elapsed.
 
-Computes the number of leap seconds that have elapsed between two days. Note that this is the sum of
-such leap seconds, so it will be 0 if (for example) there is one positive leap second and one 
-negative leap second. The ordering of the dates is important; if \a start is after \a end, then the
-value returned will be negative (for positive leap seconds).
+Computes the number of leap seconds that have elapsed between two days. Note
+that this is the sum of such leap seconds, so it will be 0 if (for example)
+there is one positive leap second and one negative leap second. The ordering of
+the dates is important; if \a start is after \a end, then the value returned
+will be negative (for positive leap seconds).
 
 */
-int iso8601_leap_elapsed(const struct iso8601_date* start, const struct iso8601_date* end);
+int iso8601_leap_elapsed(const struct iso8601_date* start,
+    const struct iso8601_date* end)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -75,17 +89,22 @@ int iso8601_leap_elapsed(const struct iso8601_date* start, const struct iso8601_
 \param new_table Array of day numbers on which leap seconds occur.
 \param new_size Number of entries in array.
 
-This function can be used to update the table of leap seconds at runtime. The \a new_table argument
-points to an array of integers, each entry being the day number containing a leap second.  The array
-must be sorted so that lower day numbers appear towards the start of the array. \a new_size gives
-the number of entries in the array. \a new_table must persist in memory as long as library functions
-are in use.
+This function can be used to update the table of leap seconds at runtime. The
+\a new_table argument points to an array of integers, each entry being the day
+number containing a leap second.  The array must be sorted so that lower day
+numbers appear towards the start of the array. \a new_size gives the number of
+entries in the array. \a new_table must persist in memory as long as library
+functions are in use.
 
-\warning If negative leap seconds are ever used, this function will not support them. There may need
-    to be an ABI change in future to solve this problem.
+\warning If negative leap seconds are ever used, this function will not support
+    them. There may need to be an ABI change in future to solve this problem.
 
 */
-void iso8601_leap_table_set(int* new_table, int new_size) __attribute__((nonnull));
+void iso8601_leap_table_set(int* new_table, int new_size)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -95,15 +114,21 @@ void iso8601_leap_table_set(int* new_table, int new_size) __attribute__((nonnull
 \retval 0 on success.
 \retval -1 on error (and see \a errno).
 
-This function attempts to load a new table of leap seconds from disk, using the filename \a fname.
-If \a fname is not specified, the system default (set at compile time) will be used.
+This function attempts to load a new table of leap seconds from disk, using the
+filename \a fname.  If \a fname is not specified, the system default (set at
+compile time) will be used.
 
-If the table is loaded successfully, it will be set with \ref iso8601_leap_table_set(). On any
-error, -1 will be returned, and \a errno will be set appropriately. If \a errno is \c EINVAL, then
-the file does not contain a valid leap second table.
+If the table is loaded successfully, it will be set with \ref
+iso8601_leap_table_set(). On any error, -1 will be returned, and \a errno will
+be set appropriately. If \a errno is \c EINVAL, then the file does not contain
+a valid leap second table.
 
 */
-int iso8601_leap_table_load(const char* fname);
+int iso8601_leap_table_load(const char* fname)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
diff --git a/src/libiso8601/400_manip.h b/src/libiso8601/400_manip.h
index b7faf39..2f45e2e 100644
--- a/src/libiso8601/400_manip.h
+++ b/src/libiso8601/400_manip.h
@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/400_manip.h
  *
- *  (c)2006, Laurence Withers, .
- *  Released under the GNU GPLv2. See file COPYING or
+ *  (c)2006-2010, Laurence Withers, .
+ *  Released under the GNU GPLv3. See file COPYING or
  *  http://www.gnu.org/copyleft/gpl.html for details.
 */
 
@@ -9,8 +9,8 @@
 
 /*! \defgroup manip Manipulation routines.
 
-This set of functions is useful for performing arithmetic etc. on dates. It uses 
-struct iso8601_elapsed to represent the magnitude of time differences.
+This set of functions is useful for performing arithmetic etc. on dates. It
+uses struct \ref iso8601_elapsed to represent the magnitude of time differences.
 
 */
 /*!@{*/
@@ -25,7 +25,11 @@ struct iso8601_elapsed to represent the magnitude of time differences.
 \retval 0 otherwise
 
 */
-int iso8601_lt(const struct iso8601_date* d1, const struct iso8601_date* d2);
+int iso8601_lt(const struct iso8601_date* d1, const struct iso8601_date* d2)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -37,7 +41,11 @@ int iso8601_lt(const struct iso8601_date* d1, const struct iso8601_date* d2);
 \retval 0 otherwise
 
 */
-int iso8601_lte(const struct iso8601_date* d1, const struct iso8601_date* d2);
+int iso8601_lte(const struct iso8601_date* d1, const struct iso8601_date* d2)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -49,7 +57,11 @@ int iso8601_lte(const struct iso8601_date* d1, const struct iso8601_date* d2);
 \retval 0 otherwise
 
 */
-int iso8601_eq(const struct iso8601_date* d1, const struct iso8601_date* d2);
+int iso8601_eq(const struct iso8601_date* d1, const struct iso8601_date* d2)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -62,7 +74,11 @@ int iso8601_eq(const struct iso8601_date* d1, const struct iso8601_date* d2);
 \retval 1 if \a d1 > \a d2
 
 */
-int iso8601_cmp(const struct iso8601_date* d1, const struct iso8601_date* d2);
+int iso8601_cmp(const struct iso8601_date* d1, const struct iso8601_date* d2)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -72,7 +88,12 @@ int iso8601_cmp(const struct iso8601_date* d1, const struct iso8601_date* d2);
 \param per Period to advance date/time by.
 
 */
-void iso8601_add_elapsed(struct iso8601_date* date, const struct iso8601_elapsed* per);
+void iso8601_add_elapsed(struct iso8601_date* date,
+    const struct iso8601_elapsed* per)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -82,7 +103,12 @@ void iso8601_add_elapsed(struct iso8601_date* date, const struct iso8601_elapsed
 \param per Period to regress date/time by.
 
 */
-void iso8601_subtract_elapsed(struct iso8601_date* date, const struct iso8601_elapsed* per);
+void iso8601_subtract_elapsed(struct iso8601_date* date,
+    const struct iso8601_elapsed* per)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -92,11 +118,17 @@ void iso8601_subtract_elapsed(struct iso8601_date* date, const struct iso8601_el
 \param per Period to advance date/time by.
 \param n Multiple of \a per.
 
-Adds \a n multiples of \a per to \a date. \a n may be 0 or negative. The result is stored in
-\a date. This is an efficient implementation which avoids loops, but it does use 64-bit arithmetic.
+Adds \a n multiples of \a per to \a date. \a n may be 0 or negative. The result
+is stored in \a date. This is an efficient implementation which avoids loops,
+but it does use 64-bit arithmetic.
 
 */
-void iso8601_add_multiple(struct iso8601_date* date, const struct iso8601_elapsed* per, int n);
+void iso8601_add_multiple(struct iso8601_date* date,
+    const struct iso8601_elapsed* per, int n)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -107,13 +139,18 @@ void iso8601_add_multiple(struct iso8601_date* date, const struct iso8601_elapse
 \param[out] per Magnitude of period elapsed between two dates. Pointer may be 0.
 \param[out] sign Set to sign of difference (-1 or +1). Pointer may be 0.
 
-This function will perform the calculation |d1 - d2|, storing the result in \a per (if
-it is not a null pointer). The sign of the result is stored in \a sign (if it is not a null 
-pointer), i.e. -1 if \a d2 > \a d1 or +1 if \a d2 <= \a d1.
+This function will perform the calculation |d1 - d2|, storing the
+result in \a per (if it is not a null pointer). The sign of the result is
+stored in \a sign (if it is not a null pointer), i.e. -1 if \a d2 > \a d1 or
++1 if \a d2 <= \a d1.
 
 */
-void iso8601_difference(const struct iso8601_date* d1, const struct iso8601_date* d2,
-    struct iso8601_elapsed* per, int* sign);
+void iso8601_difference(const struct iso8601_date* d1,
+    const struct iso8601_date* d2, struct iso8601_elapsed* per, int* sign)
+#ifndef DOXYGEN
+    __attribute__((nonnull))
+#endif
+;
 
 
 
@@ -124,13 +161,13 @@ void iso8601_difference(const struct iso8601_date* d1, const struct iso8601_date
 \param[out] remain Remainder. May be 0.
 \returns Number of times \a denom divides into \a num.
 
-This function computes the number of times that \a denom can be divided into \a num, returning that
-number. If desired, the remaining period which could not be divided can be written into \a remain.
-Uses 64-bit arithmetic internally.
+This function computes the number of times that \a denom can be divided into \a
+num, returning that number. If desired, the remaining period which could not be
+divided can be written into \a remain.  Uses 64-bit arithmetic internally.
 
 */
-int iso8601_elapsed_div(const struct iso8601_elapsed* num, const struct iso8601_elapsed* denom,
-    struct iso8601_elapsed* remain)
+int iso8601_elapsed_div(const struct iso8601_elapsed* num,
+    const struct iso8601_elapsed* denom, struct iso8601_elapsed* remain)
 #ifndef DOXYGEN
     __attribute__((nonnull(1,2)));
 #endif