Add code documentation for utilities

1 files changed, 36 insertions, 0 deletions

diff --git a/nix-utils.sh b/nix-utils.sh
index 39c7b80..7887feb 100644
--- a/nix-utils.sh
+++ b/nix-utils.sh
@@ -5,24 +5,39 @@ Red='\e[0;31m'
 Yellow='\e[0;33m'
 Green='\e[0;32m'
 
+#
+# Print on stderr, in red
+#
 stderr() {
     echo -e "${Red}[$(basename $0)]: ${*}${Color_Off}" >&2
 }
 
+#
+# Print on stdout, if verbosity is enabled, prefix in green
+#
 stdout() {
     [[ $VERBOSE -eq 1 ]] && echo -e "${Green}[$(basename $0)]:${Color_Off} $*"
 }
 
+#
+# Get the command name from a script path
+#
 scriptname_to_command() {
         echo "$1" | sed 's,^\.\/nix-script-,,' | sed 's,\.sh$,,' | \
             sed -r "s,$(dirname ${BASH_SOURCE[0]})/nix-script-,,"
 }
 
+#
+# Generate a help synopsis text
+#
 help_synopsis() {
     SCRIPT=$(scriptname_to_command $1); shift
     echo "usage: nix-script $SCRIPT $*"
 }
 
+#
+# generate a help text footnote
+#
 help_end() {
     echo -e "\tAdding '-v' before the '$1' command turns on verbosity"
     echo -e ""
@@ -31,23 +46,38 @@ help_end() {
     echo ""
 }
 
+#
+# Explain the next command
+#
 explain() {
     stdout "$*"
     $*
 }
 
+#
+# Helper for greping the current generation
+#
 grep_generation() {
     $* | grep current | sed -r 's,\s*([0-9]*)(.*),\1,'
 }
 
+#
+# get the current system generation
+#
 current_system_generation() {
     grep_generation "sudo nix-env -p /nix/var/nix/profiles/system --list-generations"
 }
 
+#
+# get the current user generation
+#
 current_user_generation() {
     grep_generation "nix-env --list-generations"
 }
 
+#
+# Ask the user whether to continue or not
+#
 continue_question() {
 	local answer
 	echo -ne "${Yellow}$1 [yN]?:${Color_Off} " >&2
@@ -56,6 +86,9 @@ continue_question() {
 	[[ "${answer}" =~ ^[Yy]$ ]] || return 1
 }
 
+#
+# Ask whether a command should be executed or not.
+#
 ask_execute() {
     q="$1"; shift
 	local answer
@@ -64,6 +97,9 @@ ask_execute() {
 	[[ ! "${answer}" =~ ^[Nn]$ ]] && eval $*
 }
 
+#
+# Helper for executing git commands in another git directory
+#
 __git() {
     DIR=$1; shift
     explain git --git-dir="$DIR/.git" --work-tree="$DIR" $*