From 51e8b0cda7f3eb834d44ec16cb7190d2fa14a057 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <philipp.gesang@intra2net.com>
Date: Fri, 5 Apr 2019 11:48:44 +0200
Subject: [PATCH] document some more timefunc member functions

---
 src/timefunc.cpp |   57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 57 insertions(+), 0 deletions(-)

diff --git a/src/timefunc.cpp b/src/timefunc.cpp
index 0883055..a4d38b8 100644
--- a/src/timefunc.cpp
+++ b/src/timefunc.cpp
@@ -1245,6 +1245,23 @@ namespace clock {
         return *this;
     }
 
+    /**
+     * @brief         Format timestamp according to the ISO standard rules.
+     *
+     * @param utc     Whether to normalize the timestamp to UTC or local time.
+     * @param date    Whether to include the date (%F).
+     * @param time    Whether to include the time (%T).
+     * @param tz      Whether to include the UTC offset (%z).
+     *
+     * @return        \c none if the formatting operation failed, the
+     *                formatted timestamp otherwise.
+     *
+     * @note          The standard allows for extending the format using
+     *                a fractional component. However, this is subject to
+     *                local conventions so we don’t support it. For more
+     *                than seconds granularity use a better suited format
+     *                like LDAP Generalized time instead.
+     */
     boost::optional<std::string>
     Time::format_iso8601 (const bool utc,
                           const bool date,
@@ -1276,6 +1293,16 @@ namespace clock {
     Time::format_date (void) const
     { return ::format_date (this->value.tv_sec); }
 
+    /**
+     * @brief         Obtain the current time wrt. the given
+     *                clock variants.
+     *
+     * @param id      Clock id.
+     * @param var     Clock variant.
+     *
+     * @return        \c none if the underlying \c clock_gettime() operation
+     *                failed, a fully initialized \c struct Time otherwise.
+     */
     boost::optional<Time>
     now (const enum type::id id, const enum type::variant var) NOEXCEPT
     {
@@ -1292,6 +1319,19 @@ namespace clock {
     zero (const enum type::id id, const enum type::variant var) NOEXCEPT
     { return Time (id, var); }
 
+    /**
+     * @brief         Standard three-way comparison for \c struct Time
+     *                relying on strict total ordering.
+     *
+     * @param t1      Comparand.
+     * @param t2      Comparand.
+     *
+     * @return        -1, 0, 1 depending on whether t1 is less-than, equal,
+     *                or greater than t2.
+     *
+     * @note          This should be used to implement the spaceship operator
+     *                (P0515R0) when we get a new compiler.
+     */
     int
     compare (const Time &t1, const Time &t2) NOEXCEPT
     {
@@ -1314,6 +1354,23 @@ namespace clock {
         return 0;
     }
 
+    /**
+     * @brief         Interpret string as timestamp according to the ISO
+     *                standard rules.
+     *
+     *                This is the inverse operation of \c format_iso8601().
+     *
+     * @param s       Input string to read. The entire string is interpreted
+     *                and it must not contain any trailing data.
+     * @param date    Whether to parse the date (%F).
+     * @param time    Whether to parse the time (%T).
+     * @param tz      Whether to parse the UTC offset (%z).
+     * @param id      Clock id to assign the result.
+     * @param var     Clock variant to assign the result.
+     *
+     * @return        \c none if the input could not be parsed according to
+     *                ISO rules, a \c struct Time otherwise.
+     */
     boost::optional<Time>
     time_of_iso8601 (const std::string        &s,
                      const bool                date,
-- 
1.7.1