doc: Add documentation for params and return values for the time module

EngineeringSoftware · Jan 26, 2024 · d4eb0ae · d4eb0ae
1 parent d7b50b3
commit d4eb0ae
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 7 deletions.
diff --git a/src/tools/bdoc.sh b/src/tools/bdoc.sh
@@ -54,11 +54,9 @@ END
                 [[ "${fun}" = "_"* ]] && continue
                 echo ".. py:function:: ${fun}"
                 echo
-                echo $(sys_function_doc "${pathf}" "${fun}")
+                sys_function_doc "${pathf}" "${fun}" || \
+                        { ctx_w $ctx "cannot get doc for ${fun}"; return $EC; }
                 echo
-                # TODO: add return and types.
-                #:return: ...
-                #:rtype: ...
         done
 }
 

diff --git a/src/util/time.sh b/src/util/time.sh
@@ -2,7 +2,7 @@
 #
 # https://github.com/EngineeringSoftware/gobash/blob/main/LICENSE
 #
-# Util time functions.
+# Util time related functions.
 
 if [ -n "${TIME_MOD:-}" ]; then return 0; fi
 readonly TIME_MOD=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
@@ -15,6 +15,9 @@ readonly TIME_MOD=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
 
 function time_now_millis() {
         # Current time in milliseconds.
+        # 
+        # :return: Current time in milliseconds.
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -29,6 +32,9 @@ function time_now_millis() {
 
 function time_now_day_of_week() {
         # Current day of the week (as a number: 1-Mon, ... 7-Sun).
+        # 
+        # :return: Current day of the week as a number.
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -38,6 +44,9 @@ function time_now_day_of_week() {
 
 function time_now_day_of_week_str() {
         # Current day of the week (as a string: Monday, ... Sunday).
+        # 
+        # :return: Current day of the week as a string.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -47,6 +56,9 @@ function time_now_day_of_week_str() {
 
 function time_now_day_of_month() {
         # Current day of the month.
+        # 
+        # :return: Current day of the month.
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -56,6 +68,9 @@ function time_now_day_of_month() {
 
 function time_now_year() {
         # Current year.
+        # 
+        # :return: Current year.
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -65,6 +80,9 @@ function time_now_year() {
 
 function time_now_month() {
         # Current month (as a number).
+        # 
+        # :return: Current month as a number.
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -74,6 +92,9 @@ function time_now_month() {
 
 function time_now_month_str() {
         # Current month (as a full string, e.g., January).
+        # 
+        # :return: Current month as a string.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -83,6 +104,9 @@ function time_now_month_str() {
 
 function time_now_iso8601() {
         # Current time in ISO 8601 format.
+        # 
+        # :return: Current time in ISO 8601 format.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
         shift 0 || { ctx_wn $ctx; return $EC; }
@@ -97,6 +121,10 @@ function time_now_iso8601() {
 
 function time_millis_to_date() {
         # Return date format for the given number in milliseconds.
+        # 
+        # :param millis: Time in milliseconds.
+        # :return: Date format.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
         local -r -i millis="${1}"
@@ -114,17 +142,25 @@ function time_millis_to_date() {
 
 function time_seconds_to_date() {
         # Convert from seconds to date format.
+        # 
+        # :param secs: Time in seconds.
+        # :return: Date format.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
-        local -r seconds="${1}"
+        local -r secs="${1}"
         shift 1 || { ctx_wn $ctx; return $EC; }
 
-        local -r as_date=$($X_DATE -d @"${seconds}")
+        local -r as_date=$($X_DATE -d @"${secs}")
         $X_DATE -d "${as_date}" +"%Y-%m-%d %H:%M:%S"
 }
 
 function time_millis_to_seconds() {
         # Convert milliseconds to seconds.
+        # 
+        # :param millis: Time in milliseconds.
+        # :return: Time in seconds.
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
         local -r millis="${1}"
@@ -135,6 +171,11 @@ function time_millis_to_seconds() {
 
 function time_duration_w() {
         # Prints duration to execute the given command.
+        # 
+        # :param marker: Marker for the log line.
+        # :param ...: Command to run and arguments.
+        # :return: Output of the command plus log line with duration in ms.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -lt 1 ] && { ctx_wn $ctx; return $EC; }
         local -r marker="${1}"
@@ -153,6 +194,10 @@ function time_duration_w() {
 
 function time_num_to_month() {
         # Convert a number to month string.
+        # 
+        # :param num: Month as a number (Jan=1).
+        # :return: Short month string.
+        # :rtype: string
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
         local -r -i num="${1}"
@@ -181,6 +226,10 @@ function time_num_to_month() {
 
 function time_month_to_num() {
         # Convert month (as a string) to number.
+        # 
+        # :param str: Month as a string (short or long).
+        # :return: Month as a number (Jan=1).
+        # :rtype: int
         local ctx; is_ctx "${1}" && ctx="${1}" && shift
         [ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
         local str="${1}"