doc: update docs with formatting, grammar and spelling fixes (amber-l…

…ang#464)

src/std/array.ab

@@ -1,5 +1,6 @@
-/// Returns index of the first value found in the specified array
-/// If the value is not found, the function returns -1
+/// Returns index of the first value found in the specified array.
+///
+/// If the value is not found, the function returns -1.
 pub fun array_first_index(array, value): Num {
     loop index, element in array {
         if value as Text == element as Text {
@@ -9,7 +10,7 @@ pub fun array_first_index(array, value): Num {
     return -1
 }
 
-/// Search the value in array and return an array with the index of the various items
+/// Searches for a value in an array and returns an array with the index of the various items.
 pub fun array_search(array, value): [Num] {
     let result = [Num]
     loop index, element in array {
@@ -20,7 +21,7 @@ pub fun array_search(array, value): [Num] {
     return result
 }
 
-/// Check if the value is in the array
+/// Checks if a value is in the array.
 pub fun includes(array, value) {
     let result = array_first_index(array, value)
     return result >= 0

src/std/date.ab

@@ -1,9 +1,15 @@
-/// EXPERIMENTAL
-/// Format a date with a special format
-/// If no date is specified, the current date is used
-/// If no format is specified, "%FT%T%Z" format is used
-/// For more info about format type "man date" on your shell or go to https://www.gnu.org/software/coreutils/date
+/// ### EXPERIMENTAL
+/// 
+/// Formats a date with a special format.
+///
+/// If no date is specified, the current date is used.
+///
+/// If no format is specified, "%FT%T%Z" format is used.
+///
+/// For more info about format type "man date" on your shell or go to <https://www.gnu.org/software/coreutils/date>.
+///
 /// Format : 
+/// ```
 /// %%     a literal %
 /// %a     locale's abbreviated weekday name (e.g., Sun)
 /// %A     locale's full weekday name (e.g., Sunday)
@@ -50,15 +56,18 @@
 /// %::z   +hh:mm:ss numeric time zone (e.g., -04:00:00)
 /// %:::z  numeric time zone with : to necessary precision (e.g., -04, +05:30)
 /// %Z     alphabetic time zone abbreviation (e.g., EDT)
-///
+/// ```
+/// 
 /// By default, date pads numeric fields with zeroes.  The following optional flags may follow '%':
 ///
+/// ```
 /// -      (hyphen) do not pad the field
 /// _      (underscore) pad with spaces
 /// 0      (zero) pad with zeros
 /// +      pad with zeros, and put '+' before future years with >4 digits
 /// ^      use upper case if possible
 /// #      use opposite case if possible
+/// ```
 pub fun date_posix(format: Text = "", date: Text = "", utc: Bool = false): Text? {
     if format == "": format = "%FT%T%Z"
     if date == "": date = unsafe $date +"%FT%T%Z"$
@@ -69,35 +78,43 @@ pub fun date_posix(format: Text = "", date: Text = "", utc: Bool = false): Text?
     }    
 }
 
-/// Return current timestamp (seconds since the Epoch (1970-01-01 00:00 UTC))
+/// Returns the current timestamp (seconds since the Epoch (1970-01-01 00:00 UTC)).
 #[allow_absurd_cast]
 pub fun now(): Num {
     return unsafe $date +%s$ as Num
 }
 
-/// EXPERIMENTAL
-/// Add value to date.
-/// If no date is specified, the current date is used
-/// Ex : date_add("+3 days")
-/// You can use : 
-/// (+/-)
-/// years
-/// months
-/// days
-/// hours
-/// minutes
-/// seconds
+/// ### EXPERIMENTAL
+///
+/// Adds a value to a date.
+/// 
+/// If no date is specified, the current date is used.
+/// 
+/// Example : `date_add("+3 days")`
+/// 
+/// You can use (+/-): 
+///
+/// - years
+/// - months
+/// - days
+/// - hours
+/// - minutes
+/// - seconds
 pub fun date_add(add:Text, date:Text = "", utc: Bool = false): Text? {
     if date == "": date = unsafe $date +"%FT%T%Z"$
     return date_posix("", "{date_posix("%F", date, utc)?} {add} {date_posix("%T", date, utc)?}", utc)?
 }
 
-/// EXPERIMENTAL
-// Compare 2 date
-// Return 1 if date_a is after date_b
-// Return 0 if date_a and date_b is the same
-// Return -1 if date_b is after date_a
-// If date_b is not provided, current date will be used
+/// ### EXPERIMENTAL
+/// Compares two dates.
+///
+/// Returns 1 if date_a is after date_b.
+///
+/// Returns 0 if date_a and date_b is the same.
+/// 
+/// Returns -1 if date_b is after date_a.
+///
+/// If date_b is not provided, current date will be used.
 #[allow_absurd_cast]
 pub fun date_compare(date_a: Text, date_b: Text = "", utc: Bool = false): Num? {
     if date_b == "": date_b = unsafe date_posix("", "", utc)
@@ -106,4 +123,4 @@ pub fun date_compare(date_a: Text, date_b: Text = "", utc: Bool = false): Num? {
     if timestamp_a > timestamp_b: return 1
     if timestamp_a == timestamp_b: return 0
     if timestamp_a < timestamp_b: return -1
-}
+}

src/std/env.ab

@@ -16,61 +16,62 @@ pub fun get_env_var(var: Text, file: Text = ".env"): Text {
     return ""
 }
 
-/// Load the env file in the environment, using `xargs`
+/// Loads the env file in the environment, using `xargs`.
 pub fun load_env_file(file: Text = ".env"): Null {
     unsafe $export "\$(xargs < {file})" > /dev/null$
 }
 
-/// Check if a variable inside the Shell session exist
+/// Checks if a variable inside the shell session exists.
 pub fun shell_isset(name: Text): Bool {
     $[[ ! -z \$\{!{nameof name}+z} ]]$ failed {
         return false
     }
     return true
 }
 
-/// Set a constant inside the Shell session
+/// Sets a constant inside the shell session.
 pub fun shell_constant_set(name: Text, val: Text): Null? {
     $readonly \${nameof name}="\${nameof val}" 2> /dev/null$?
 }
 
-/// Get a constant inside the Shell session
+/// Gets a constant inside the shell session.
 pub fun shell_constant_get(name: Text): Text? {
     return $echo \$\{!{nameof name}}$?
 }
 
-/// Set a constant inside the Shell session
+/// Sets a constant inside the shell session.
 pub fun shell_var_set(name: Text, val: Text): Null? {
     $export \${nameof name}="\${nameof val}" 2> /dev/null$?
 }
 
-/// Get a constant inside the Shell session
+/// Gets a constant inside the shell session.
 pub fun shell_var_get(name: Text): Text? {
     return $echo \$\{!{nameof name}}$?
 }
 
-/// Remove a variable inside the Shell session
+/// Removes a variable inside the shell session.
 pub fun shell_unset(name: Text): Null? {
     $unset {name}$?
 }
 
-/// Check if the command exist
+/// Checks if a command exists.
 pub fun is_command(command: Text): Bool {
     $[ -x "\$(command -v {command})" ]$ failed {
         return false
     }
     return true
 }
 
-/// Create a prompt and return the value
+/// Creates a prompt and returns the value.
 pub fun input(prompt: Text): Text {
     unsafe $printf "\${nameof prompt}"$
     unsafe $read$
     return "\$REPLY"
 }
 
-/// Confirm prompt (Yes/No), return true if choice is Yes
-/// "No" is the default choice, set default_yes to true for "Yes" as default choice
+/// Creates a confirm prompt (Yes/No), and returns true if the choice is Yes.
+///
+/// "No" is the default choice, set default_yes to true for "Yes" as default choice.
 pub fun confirm(prompt: Text, default_yes: Bool = false): Bool {
     let choice_default = default_yes then " [\x1b[1mY/\x1b[0mn]" else " [y/\x1b[1mN\x1b[0m]"
     unsafe {
@@ -82,18 +83,18 @@ pub fun confirm(prompt: Text, default_yes: Bool = false): Bool {
     return result == "y" or (result == "" and default_yes)
 }
 
-/// Checks if the command has failed
+/// Checks if the command has failed.
 pub fun has_failed(command: Text): Bool {
     unsafe silent $eval {command}$
     return status != 0
 }
 
-/// Close the script
+/// Closes the script.
 pub fun exit(code: Num): Null {
     unsafe $exit "{code}"$
 }
 
-/// Check if the script is running with a user with root permission
+/// Checks if the script is running with a user with root permission.
 pub fun is_root(): Bool {
     if unsafe $id -u$ == "0" {
         return true
@@ -102,58 +103,58 @@ pub fun is_root(): Bool {
     return false
 }
 
-/// `printf` the text following the arguments
+/// `printf` the text following the arguments.
 pub fun printf(format: Text, args: [Text] = [""]): Null {
     unsafe ${nameof args}=("{format}" "\$\{{nameof args}[@]}")$
     unsafe $printf "\$\{{nameof args}[@]}"$
 }
 
-/// Escape the text to be used with `printf`
+/// Escapes the text to be used with `printf`.
 pub fun printf_escape(text: Text): Text {
     return unsafe $echo \${nameof text} | sed -e 's/\\\\/\\\\\\\\/g' -e "s/%/%%/g"$
 }
 
-/// Prepare a text with formatting options for `printf`
+/// Prepares a text with formatting options for `printf`.
 pub fun text_shell(message: Text, style: Num, fg: Num, bg: Num): Text {
     return "\x1b[{style};{fg};{bg}m{printf_escape(message)}\x1b[0m"
 }
 
-/// Return a text as bold
+/// Returns a text as bold.
 pub fun text_bold(message: Text): Text {
     return "\x1b[1m{printf_escape(message)}\x1b[0m"
 }
 
-/// Return a text as italic
+/// Returns a text as italic.
 pub fun text_italic(message: Text): Text {
     return "\x1b[3m{printf_escape(message)}\x1b[0m"
 }
 
-/// Return a text as underlined
+/// Returns a text as underlined.
 pub fun text_underlined(message: Text): Text {
     return "\x1b[4m{printf_escape(message)}\x1b[0m"
 }
 
-/// Print a text with a specified color
+/// Prints a text with a specified color.
 pub fun color_echo(message: Text, color: Num): Null {
     printf("\x1b[{color as Text}m%s\x1b[0m\n", [message])
 }
 
-/// Print a text as Info
+/// Prints a text as a info message.
 pub fun echo_info(message: Text): Null {
     printf("\x1b[1;3;97;44m %s \x1b[0m\n", [message])
 }
 
-/// Print a text as Success
+/// Prints a text as a success message.
 pub fun echo_success(message: Text): Null {
     printf("\x1b[1;3;97;42m %s \x1b[0m\n", [message])
 }
 
-/// Print a text as Warning
+/// Prints a text as a warning message.
 pub fun echo_warning(message: Text): Null {
     printf("\x1b[1;3;97;43m %s \x1b[0m\n", [message])
 }
 
-/// Print a text as Error and exit if the status code is greater than 0
+/// Prints a text as a error and exits if the status code is greater than 0.
 pub fun error(message: Text, exit_code: Num = 1): Null {
     printf("\x1b[1;3;97;41m %s \x1b[0m\n", [message])
     if exit_code > 0 : exit(exit_code)

src/std/fs.ab

@@ -1,38 +1,40 @@
-/// Check if directory exists
+/// Checks if a directory exists.
 pub fun dir_exist(path) {
     $[ -d "{path}" ]$ failed {
         return false
     }
     return true
 }
 
-/// Check if file exists
+/// Checks if a file exists.
 pub fun file_exist(path) {
     $[ -f "{path}" ]$ failed {
         return false
     }
     return true
 }
 
-/// Get the file content
+/// Gets file contents from a path.
 pub fun file_read(path) {
     return $< "{path}"$?
 }
 
-/// Write the content to the file
+/// Writes content to a file.
 /// Doesn't check if the file exist
 pub fun file_write(path, content) {
     return $echo "{content}" > "{path}"$?
 }
 
-/// Append the content to the file
-/// Doesn't check if the file exist
+/// Appends content to a file.
+///
+/// Doesn't check if the file exists.
 pub fun file_append(path, content) {
     return $echo "{content}" >> "{path}"$?
 }
 
-/// Create a symbolic link
-/// If the file doens't exist return a boolean and print a message
+/// Creates a symbolic link.
+///
+/// If the file doesn't exist, it returns a boolean and prints a message.
 pub fun create_symbolic_link(origin: Text, destination: Text): Bool {
     if file_exist(origin) {
         unsafe $ln -s "{origin}" "{destination}"$
@@ -43,15 +45,16 @@ pub fun create_symbolic_link(origin: Text, destination: Text): Bool {
     return false
 }
 
-/// Create a directory with all intermediate directories as required
+/// Creates a directory with all parent directories as required.
 pub fun create_dir(path: Text): Null {
     if not dir_exist(path) {
         unsafe $mkdir -p "{path}"$
     }
 }
 
-/// Set the file as executable
-/// If the file doesn't exist return a boolean and print a message
+/// Sets a file as executable.
+///
+/// If the file doesn't exist, it returns a boolean and prints a message.
 pub fun make_executable(path: Text): Bool {
     if file_exist(path) {
         unsafe $chmod +x "{path}"$
@@ -62,8 +65,9 @@ pub fun make_executable(path: Text): Bool {
     return false
 }
 
-/// Change the owner of the file
-/// If the file doesn't exist return false
+/// Changes the owner of a file.
+///
+/// If the file doesn't exist, it returns `false`
 pub fun change_owner(user: Text, path: Text): Bool {
     if file_exist(path) or dir_exist(path) {
         unsafe $chown -R "{user}" "{path}"$

src/std/http.ab

@@ -2,8 +2,7 @@ import * from "std/env"
 
 /// Downloads a file from a given URL and saves it to a specified path using available command-line tools.
 ///
-/// This function attempts to download a file from the provided URL and save it to the specified path.
-/// It checks for the availability of common command-line tools (`curl`, `wget`, and `aria2c`) and uses the first available tool to perform the download.
+/// It checks for the availability of common command-line tools (`curl`, `wget`, and `aria2c`, in order) and uses the first available tool to perform the download.
 /// If none of the tools are available, the function returns `false`.
 pub fun download(url: Text, path: Text): Bool {
     if {