Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Jan 26, 2024
+54 −7
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions src/tools/bdoc.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand Down
55 changes: 52 additions & 3 deletions src/util/time.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 )
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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; }
Expand All @@ -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}"
Expand All @@ -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}"
Expand All @@ -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}"
Expand All @@ -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}"
Expand Down Expand Up @@ -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}"
Expand Down
Loading