include/ruby/internal/intern/time.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

include/ruby/internal/intern/time.h

@@ -26,6 +26,7 @@
 # include <time.h>              /* for time_t */
 #endif
 
+#include "ruby/internal/attr/nonnull.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/value.h"
 
@@ -35,15 +36,124 @@ struct timespec;
 struct timeval;
 
 /* time.c */
-void rb_timespec_now(struct timespec *);
-VALUE rb_time_new(time_t, long);
-VALUE rb_time_nano_new(time_t, long);
-VALUE rb_time_timespec_new(const struct timespec *, int);
-VALUE rb_time_num_new(VALUE, VALUE);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Fills the current time into the given struct.
+ *
+ * @param[out]  ts                   Return buffer.
+ * @exception   rb_eSystemCallError  Access denied for hardware clock.
+ * @post        Current time is stored in `*ts`.
+ */
+void rb_timespec_now(struct timespec *ts);
+
+/**
+ * Creates  an  instance of  ::rb_cTime  with  the  given  time and  the  local
+ * timezone.
+ *
+ * @param[in]  sec             Seconds since the UNIX epoch.
+ * @param[in]  usec            Subsecond part, in microseconds resolution.
+ * @exception  rb_eRangeError  Cannot express the time.
+ * @return     An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_new(time_t sec, long usec);
+
+/**
+ * Identical  to  rb_time_new(), except  it  accepts  the time  in  nanoseconds
+ * resolution.
+ *
+ * @param[in]  sec             Seconds since the UNIX epoch.
+ * @param[in]  nsec            Subsecond part, in nanoseconds resolution.
+ * @exception  rb_eRangeError  Cannot express the time.
+ * @return     An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_nano_new(time_t sec, long nsec);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Creates an instance of ::rb_cTime, with given time and offset.
+ *
+ * @param[in]  ts            Time specifier.
+ * @param[in]  offset        Offset specifier, can take following values:
+ *                           - `INT_MAX`: `ts` is in local time.
+ *                           - `INT_MAX - 1`: `ts` is in UTC.
+ *                           - `-86400` to `86400`: fixed timezone.
+ * @exception  rb_eArgError  Malformed `offset`.
+ * @return     An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_timespec_new(const struct timespec *ts, int offset);
+
+/**
+ * Identical to rb_time_timespec_new(), except it  takes Ruby values instead of
+ * C structs.
+ *
+ * @param[in]  timev         Something numeric.  Currently Integers, Rationals,
+ *                           and Floats are accepted.
+ * @param[in]  off           Offset  specifier.  As  of  2.7  this argument  is
+ *                           heavily  extended  to   take  following  kinds  of
+ *                           objects:
+ *                             - ::RUBY_Qundef ... means UTC.
+ *                             - ::rb_cString ... "+12:34" etc.
+ *                             - A mysterious  "zone" object.  This  is largely
+ *                               undocumented.  However the  initial intent was
+ *                               that       we       want       to       accept
+ *                               `ActiveSupport::TimeZone`  here.   Other  gems
+ *                               could also be possible...   But how to make an
+ *                               acceptable class is beyond this document.
+ * @exception  rb_eArgError  Malformed `off`.
+ * @return     An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_num_new(VALUE timev, VALUE off);
+
+/**
+ * Creates  a  "time  interval".   This   basically  converts  an  instance  of
+ * ::rb_cNumeric  into  a struct  `timeval`,  but  for instance  negative  time
+ * interval must not exist.
+ *
+ * @param[in]  num             An instance of ::rb_cNumeric.
+ * @exception  rb_eArgError    `num` is negative.
+ * @exception  rb_eRangeError  `num` is out of range of `timeval::tv_sec`.
+ * @return     A struct that represents the identical time to `num`.
+ */
 struct timeval rb_time_interval(VALUE num);
+
+/**
+ * Converts an  instance of rb_cTime  to a  struct timeval that  represents the
+ * identical point of time.  It can also take something numeric; would consider
+ * it as a UNIX time then.
+ *
+ * @param[in]  time            Instance of either ::rb_cTime or ::rb_cNumeric.
+ * @exception  rb_eRangeError  `time` is out of range of `timeval::tv_sec`.
+ * @return     A struct that represents the identical time to `num`.
+ */
 struct timeval rb_time_timeval(VALUE time);
+
+/**
+ * Identical to rb_time_timeval(), except for return type.
+ *
+ * @param[in]  time            Instance of either ::rb_cTime or ::rb_cNumeric.
+ * @exception  rb_eRangeError  `time` is out of range of `timeval::tv_sec`.
+ * @return     A struct that represents the identical time to `num`.
+ */
 struct timespec rb_time_timespec(VALUE time);
+
+/**
+ * Identical to rb_time_interval(), except for return type.
+ *
+ * @param[in]  num             An instance of ::rb_cNumeric.
+ * @exception  rb_eArgError    `num` is negative.
+ * @exception  rb_eRangeError  `num` is out of range of `timespec::tv_sec`.
+ * @return     A struct that represents the identical time to `num`.
+ */
 struct timespec rb_time_timespec_interval(VALUE num);
+
+/**
+ * Queries the  offset, in seconds  between the time zone  of the time  and the
+ * UTC.
+ *
+ * @param[in]  time  An instance of ::rb_cTime.
+ * @return     Numeric offset.
+ */
 VALUE rb_time_utc_offset(VALUE time);
 
 RBIMPL_SYMBOL_EXPORT_END()

time.c

@@ -2474,11 +2474,6 @@ rb_time_nano_new(time_t sec, long nsec)
     return time_new_timew(rb_cTime, nsec2timew(sec, nsec));
 }
 
-/**
- * Returns a time object with UTC/localtime/fixed offset
- *
- * offset is -86400 < fixoff < 86400 or INT_MAX (localtime) or INT_MAX-1 (utc)
- */
 VALUE
 rb_time_timespec_new(const struct timespec *ts, int offset)
 {