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

@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/100_types.h
  *
- *  (c)2006, Laurence Withers, <l@lwithers.me.uk>.
+ *  (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
- *  Released under the GNU GPLv2. See file COPYING or
+ *  Released under the GNU GPLv3. See file COPYING or
  *  http://www.gnu.org/copyleft/gpl.html for details.
 */
 
@@ -9,12 +9,13 @@
 
 /*! \brief Date/time point.
 
-This structure contains the details to represent a specific instant on the UTC timescale. It uses
+This structure contains the details to represent a specific instant on the UTC
-Jan 1, year 0000 as the origin (when \a day will be 0). \a sec is the number of seconds elapsed
+timescale. It uses Jan 1, year 0000 as the origin (when \a day will be 0). \a
-since start of day, and \a nsec is the number of nanoseconds elapsed since the start of the current
+sec is the number of seconds elapsed since start of day, and \a nsec is the
-second.
+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 {
@@ -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
+This enumeration will record how precisely the date was specified, as well as
-allows the library to determine the earliest and latest dates that could possibly be represented
+the format in use. It allows the library to determine the earliest and latest
-with the given input and also allows the output format to match the input format.
+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
+This enumeration records how precisely the time was specified as well as its
-format will record whether it was the hour, minute or second that was specified with a fractional
+format. The fractional format will record whether it was the hour, minute or
-part, allowing a processed date/time to be presented to the user in the format it was originally
+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
+This structure simply records details related to the formatting (and precision)
-structure. The structure can be filled out by the parser so that a program's output can match
+of a date/time structure. The structure can be filled out by the parser so that
-the format of its input. Alternatively it can be controlled by the program to provide a consistent
+a program's output can match the format of its input. Alternatively it can be
-output format.
+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.
+This structure contains the details of an elapsed time period, split into
-None of its components can ever be negative. This is only capable of representing short (compared to
+seconds and nanoseconds.  None of its components can ever be negative. This is
-struct iso8601_date's range) periods of up to approximately 136 years.
+only capable of representing short (compared to struct iso8601_date's range)
+periods of up to approximately 136 years.
 
 */
 struct iso8601_elapsed {

src/libiso8601/200_parser.h

@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/200_parser.h
  *
- *  (c)2006, Laurence Withers, <l@lwithers.me.uk>.
+ *  (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
- *  Released under the GNU GPLv2. See file COPYING or
+ *  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
+These routines are used for parsing an ISO8601 date/time string into the
-to represent them, and for validating such dates/times.
+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] earliest The earliest possible time the string could represent. May
-\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.
+\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
+Parses a string containing the ISO8601 date/time. Deals with any format of
-the details in \a details. The time may be partial, in which case this function returns the earliest
+date, optionally storing the details in \a details. The time may be partial, in
-and latest times that could possibly be represented by the string.
+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,
+int iso8601_parse(const char* str, struct iso8601_date* earliest,
-    struct iso8601_details* details);
+    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
+Formats and prints an ISO8601 date, optionally using the details in \a details.
-a null-terminated result, even if that means truncating the output to fit the buffer.
+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
+Checks the details of \a date to ensure that they are sensible. This involves
-is in the range 0 to 86399 (or 86400 if there is a leap second), and that \a nsec is in the range 0
+checking that \a sec is in the range 0 to 86399 (or 86400 if there is a leap
-to 999999999.
+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
 */

src/libiso8601/400_c_library.h

@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/400_c_library.h
  *
- *  (c)2006, Laurence Withers, <l@lwithers.me.uk>.
+ *  (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
- *  Released under the GNU GPLv2. See file COPYING or
+ *  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
+Retrieves the current time from the system clock, storing it into \a date and
-parameters optional).
+\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
+Attempts to set the system clock using \c clock_settime(), falling back to \c
-user will need the \c CAP_SYS_TIME capability to set the clock, otherwise \a errno will be set to
+settimeofday(). The user will need the \c CAP_SYS_TIME capability to set the
-\c EPERM.
+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
 */

src/libiso8601/400_calc.h

@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/400_calc.h
  *
- *  (c)2006, Laurence Withers, <l@lwithers.me.uk>.
+ *  (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
- *  Released under the GNU GPLv2. See file COPYING or
+ *  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,
+This set of functions is useful for converting dates and times into formats
-and vice versa.
+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
+Converts the date specified in \a year, \a month and \a day into \a date.
-or \a nsec time members of \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
+Converts the date specified into \a year and \a oday into \a date.
-\a nsec time members of \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
+Converts the time stored in \a date into wall clock format, storing the result
-and \a sec.
+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
+Converts the time as specified by \a hour, \a min and \a sec, storing the
-not touch the \a day (date) member of \a date.
+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
 */

src/libiso8601/400_leap.h

@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/400_leap.h
  *
- *  (c)2006, Laurence Withers, <l@lwithers.me.uk>.
+ *  (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
- *  Released under the GNU GPLv2. See file COPYING or
+ *  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
+A set of functions for explicitly dealing with leap seconds. All library
-leap second aware, but there are occasions when leap seconds must be dealt with explicitly. These
+functions are implicitly leap second aware, but there are occasions when leap
-functions permit this.
+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
+Internally, leap seconds are represented as a table of day numbers; each day
-table means that the corresponding day has 86401 seconds (a leap second).
+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
+\note The library does not (yet) have support for negative leap seconds. This
-    should a day with a negative leap second ever come. This will need to addressed in the API as
+    support will be added should a day with a negative leap second ever come.
-    the current API does not support loading a table of negative leap seconds.
+    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
+It is possible to create a disk file containing an updated table and to load
-\ref iso8601_leap_table_load (or to explicitly use an existing in-memory table with
+that file using \ref iso8601_leap_table_load (or to explicitly use an existing
-\ref iso8601_leap_table_set). The format of the on-disk file is:
+in-memory table with \ref iso8601_leap_table_set). The format of the on-disk
+file is:
 
 <pre># 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
+Returns the duration of a day \a date, in seconds. This function takes leap
-may be used to determine if a day contains a leap second or not.
+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
+\note There have not yet been any days requiring a negative leap second, so at
-    never be returned.
+    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
+Computes the number of leap seconds that have elapsed between two days. Note
-such leap seconds, so it will be 0 if (for example) there is one positive leap second and one 
+that this is the sum of such leap seconds, so it will be 0 if (for example)
-negative leap second. The ordering of the dates is important; if \a start is after \a end, then the
+there is one positive leap second and one negative leap second. The ordering of
-value returned will be negative (for positive leap seconds).
+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
+This function can be used to update the table of leap seconds at runtime. The
-points to an array of integers, each entry being the day number containing a leap second.  The array
+\a new_table argument points to an array of integers, each entry being the day
-must be sorted so that lower day numbers appear towards the start of the array. \a new_size gives
+number containing a leap second.  The array must be sorted so that lower day
-the number of entries in the array. \a new_table must persist in memory as long as library functions
+numbers appear towards the start of the array. \a new_size gives the number of
-are in use.
+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
+\warning If negative leap seconds are ever used, this function will not support
-    to be an ABI change in future to solve this problem.
+    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.
+This function attempts to load a new table of leap seconds from disk, using the
-If \a fname is not specified, the system default (set at compile time) will be used.
+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
+If the table is loaded successfully, it will be set with \ref
-error, -1 will be returned, and \a errno will be set appropriately. If \a errno is \c EINVAL, then
+iso8601_leap_table_set(). On any error, -1 will be returned, and \a errno will
-the file does not contain a valid leap second table.
+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
+;
 
 
 

src/libiso8601/400_manip.h

@@ -1,7 +1,7 @@
 /* libiso8601/src/libiso8601/400_manip.h
  *
- *  (c)2006, Laurence Withers, <l@lwithers.me.uk>.
+ *  (c)2006-2010, Laurence Withers, <l@lwithers.me.uk>.
- *  Released under the GNU GPLv2. See file COPYING or
+ *  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 
+This set of functions is useful for performing arithmetic etc. on dates. It
-struct iso8601_elapsed to represent the magnitude of time differences.
+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 &gt; \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
+Adds \a n multiples of \a per to \a date. \a n may be 0 or negative. The result
-\a date. This is an efficient implementation which avoids loops, but it does use 64-bit arithmetic.
+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 <code>|d1 - d2|</code>, storing the result in \a per (if
+This function will perform the calculation <code>|d1 - d2|</code>, storing the
-it is not a null pointer). The sign of the result is stored in \a sign (if it is not a null 
+result in \a per (if it is not a null pointer). The sign of the result is
-pointer), i.e. -1 if \a d2 &gt; \a d1 or +1 if \a d2 &lt;= \a d1.
+stored in \a sign (if it is not a null pointer), i.e. -1 if \a d2 &gt; \a d1 or
++1 if \a d2 &lt;= \a d1.
 
 */
-void iso8601_difference(const struct iso8601_date* d1, const struct iso8601_date* d2,
+void iso8601_difference(const struct iso8601_date* d1,
-    struct iso8601_elapsed* per, int* sign);
+    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
+This function computes the number of times that \a denom can be divided into \a
-number. If desired, the remaining period which could not be divided can be written into \a remain.
+num, returning that number. If desired, the remaining period which could not be
-Uses 64-bit arithmetic internally.
+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,
+int iso8601_elapsed_div(const struct iso8601_elapsed* num,
-    struct iso8601_elapsed* remain)
+    const struct iso8601_elapsed* denom, struct iso8601_elapsed* remain)
 #ifndef DOXYGEN
     __attribute__((nonnull(1,2)));
 #endif