From 7e7b05fcf712031535f571f12521f27a52d19e14 Mon Sep 17 00:00:00 2001
From: Milos Gligoric <gliga@users.noreply.github.com>
Date: Thu, 1 Feb 2024 09:12:34 -0600
Subject: [PATCH] doc: Include documentation for several sys functions (#15)

---
 src/lang/sys.sh      | 51 +++++++++++++++++++++++++++++++++++++++++---
 src/lang/sys_test.sh | 17 +++++++++------
 2 files changed, 59 insertions(+), 9 deletions(-)

diff --git a/src/lang/sys.sh b/src/lang/sys.sh
index 0ebe9f7..10190f2 100644
--- a/src/lang/sys.sh
+++ b/src/lang/sys.sh
@@ -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 )
@@ -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; }
@@ -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; }
@@ -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; }
@@ -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}"
@@ -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; }
@@ -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; }
@@ -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}"
@@ -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}"
@@ -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}"
@@ -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; }
@@ -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; }
@@ -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; }
@@ -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; }
diff --git a/src/lang/sys_test.sh b/src/lang/sys_test.sh
index 1e57633..536181d 100644
--- a/src/lang/sys_test.sh
+++ b/src/lang/sys_test.sh
@@ -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