Skip to content

Commit

Permalink
doc: Include documentation for several sys functions (#15)
Browse files Browse the repository at this point in the history
  • Loading branch information
@gliga
gliga authored Feb 1, 2024
1 parent 7d41b10 commit 7e7b05f
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 9 deletions.
51 changes: 48 additions & 3 deletions src/lang/sys.sh
View file
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 functions closer to the system.
# Util functions related to the system.

if [ -n "${SYS_MOD:-}" ]; then return 0; fi
readonly SYS_MOD=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
Expand All @@ -20,7 +20,10 @@ readonly SYS_SUFFIX="-dev"
# Functions.

function sys_version() {
# Version.
# Return gobash version.
#
# :return: gobash version.
# :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 @@ -29,7 +32,10 @@ function sys_version() {
}

function sys_repo_path() {
# Root dir for this repo.
# Return the root dir for this repository.
#
# :return: Root directory for this repository.
# :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 @@ -39,6 +45,9 @@ function sys_repo_path() {

function sys_stack_trace() {
# Print stack trace.
#
# :return: Stack trace.
# :rtype: strings
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
shift 0 || { ctx_wn $ctx; return $EC; }
Expand All @@ -54,6 +63,10 @@ function sys_stack_trace() {

function sys_is_on_stack() {
# Check if the function name is on stack.
#
# :param name: Name of a function.
# :return: true/0 if function is on stack; false/1 otherwise
# :rtype: bool
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
local -r name="${1}"
Expand All @@ -64,6 +77,9 @@ function sys_is_on_stack() {

function sys_bash_files() {
# List all files in this library that start with #!/bin/bash.
#
# :return: List of files in this library.
# :rtype: strings
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
shift 0 || { ctx_wn $ctx; return $EC; }
Expand All @@ -78,6 +94,9 @@ function sys_bash_files() {

function sys_functions() {
# List all functions in this library (excluding test files).
#
# :return: List of functions in this library.
# :rtype: strings
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
shift 0 || { ctx_wn $ctx; return $EC; }
Expand All @@ -89,6 +108,10 @@ function sys_functions() {

function sys_functions_in_file() {
# List all functions in the given file.
#
# :param pathf: Path to a file.
# :return: List of functions in the file.
# :rtype: strings
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 1 ] && { ctx_wn $ctx; return $EC; }
local -r pathf="${1}"
Expand All @@ -101,6 +124,11 @@ function sys_functions_in_file() {

function sys_function_doc_lines() {
# Compute number of doc lines for the given function.
#
# :param pathf: Path to a file.
# :param func: Function name.
# :return: Number of doc lines for the function in the file.
# :rtype: int
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 2 ] && { ctx_wn $ctx; return $EC; }
local -r pathf="${1}"
Expand All @@ -123,6 +151,11 @@ function sys_function_doc_lines() {

function sys_function_doc() {
# Extract documentation for the given function.
#
# :param pathf: Path to a file.
# :param func: Function name.
# :return: Documentation for the function in the file.
# :rtype: strings
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 2 ] && { ctx_wn $ctx; return $EC; }
local -r pathf="${1}"
Expand All @@ -142,6 +175,9 @@ function sys_function_doc() {

function sys_line_num() {
# Return line number from which this func was called.
#
# :return: Line number from which this function was called.
# :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 @@ -152,6 +188,9 @@ function sys_line_num() {
function sys_line_prev() {
# Return content of the line before the one from which this
# function is invoked.
#
# :return: Line before the one from which this function is invoked.
# :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 @@ -166,6 +205,9 @@ function sys_line_prev() {
function sys_line_next() {
# Return content of the line after the one from which this
# function is invoked.
#
# :return: Line after the one from which this function is invoked.
# :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 @@ -179,6 +221,9 @@ function sys_line_next() {

function sys_has_connection() {
# Return 0 if there is connection to the web; 1 otherwise.
#
# :return: true/0 if there is connection to the web; false/1 otherwise.
# :rtype: bool
local ctx; is_ctx "${1}" && ctx="${1}" && shift
[ $# -ne 0 ] && { ctx_wn $ctx; return $EC; }
shift 0 || { ctx_wn $ctx; return $EC; }
Expand Down
17 changes: 11 additions & 6 deletions src/lang/sys_test.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,23 +77,28 @@ function test_sys_function_doc_lines() {

val=$(sys_function_doc_lines "${script}" "sys_version") || \
assert_fail
assert_eq 1 "${val}"
assert_eq 4 "${val}"

val=$(sys_function_doc_lines "${script}" "sys_line_prev") || \
assert_fail
assert_eq 2 "${val}"
assert_eq 5 "${val}"
}
readonly -f test_sys_function_doc_lines

function test_sys_function_doc() {
local -r script="$(sys_repo_path)/src/lang/sys.sh"
local val
local actual

val=$(sys_function_doc "${script}" "sys_version") || \
actual=$(sys_function_doc "${script}" "sys_version") || \
assert_fail
assert_eq "Version." "${val}"

val=$(sys_function_doc "${script}" "sys_line_prev") || \
local expected="Return gobash version.
:return: gobash version.
:rtype: string"
assert_eq "${expected}" "${actual}"

actual=$(sys_function_doc "${script}" "sys_line_prev") || \
assert_fail
}
readonly -f test_sys_function_doc

0 comments on commit 7e7b05f

Please sign in to comment.