More documentation

ghcup

@@ -31,21 +31,68 @@
 
 ## global variables ##
 
+# @VARIABLE: VERSION
+# @DESCRIPTION:
+# Version of this script.
 VERSION=0.0.1
+
+# @VARIABLE: SCRIPT
+# @DESCRIPTION:
+# Name of this script.
 SCRIPT="$(basename "$0")"
+
+# @VARIABLE: VERBOSE
+# @DESCRIPTION:
+# Whether to print verbose messages in this script.
 VERBOSE=false
+
+# @VARIABLE: FORCE
+# @DESCRIPTION:
+# Whether to force installation and overwrite files.
 FORCE=false
+
+# @VARIABLE: INSTALL_BASE
+# @DESCRIPTION:
+# The main install directory where all ghcup stuff happens.
 INSTALL_BASE="$HOME/.ghcup"
+
+# @VARIABLE: GHC_LOCATION
+# @DESCRIPTION:
+# The location where ghcup will install different ghc versions.
 GHC_LOCATION="$INSTALL_BASE/ghc"
+
+# @VARIABLE: BIN_LOCATION
+# @DESCRIPTION:
+# The location where ghcup will create symlinks for GHC binaries.
 BIN_LOCATION="$INSTALL_BASE/bin"
+
+# @VARIABLE: DOWNLOADER
+# @DESCRIPTION:
+# What program to use for downloading files.
 DOWNLOADER="curl"
+
+# @VARIABLE: DOWNLOADER_OPTS
+# @DESCRIPTION:
+# Options passed to the download program.
 DOWNLOADER_OPTS="--fail -O"
+
+# @VARIABLE: SCRIPT_UPDATE_URL
+# @DESCRIPTION:
+# Location to update this script from.
 SCRIPT_UPDATE_URL="https://raw.githubusercontent.com/hasufell/ghcup/master/ghcup"
+
+# @VARIABLE: GHC_DOWNLOAD_BASEURL
+# @DESCRIPTION:
+# Base URL for all GHC tarballs.
 GHC_DOWNLOAD_BASEURL="https://downloads.haskell.org/~ghc"
 
 
 ## print help ##
 
+# @FUNCTION: usage
+# @DESCRIPTION:
+# Print the help message for 'ghcup' to STDERR
+# and exit the script with status code 1.
 usage() {
     (>&2 echo "ghcup ${VERSION}
 GHC up toolchain installer
@@ -73,6 +120,10 @@ DISCUSSION:
     exit 1
 }
 
+# @FUNCTION: install_usage
+# @DESCRIPTION:
+# Print the help message for 'ghcup install' to STDERR
+# and exit the script with status code 1.
 install_usage() {
     (>&2 echo "ghcup-install
 Install the specified GHC version
@@ -95,6 +146,10 @@ DISCUSSION:
     exit 1
 }
 
+# @FUNCTION: set_usage
+# @DESCRIPTION:
+# Print the help message for 'ghcup set' to STDERR
+# and exit the script with status code 1.
 set_usage() {
     (>&2 echo "ghcup-set
 Set the currently active GHC to the specified version
@@ -116,6 +171,10 @@ DISCUSSION:
     exit 1
 }
 
+# @FUNCTION: self_update_usage
+# @DESCRIPTION:
+# Print the help message for 'ghcup self-update' to STDERR
+# and exit the script with status code 1.
 self_update_usage() {
     (>&2 echo "ghcup-self-update
 Update the ghcup script in-place
@@ -132,7 +191,10 @@ ARGS:
     exit 1
 }
 
-
+# @FUNCTION: show_usage
+# @DESCRIPTION:
+# Print the help message for 'ghcup show' to STDERR
+# and exit the script with status code 1.
 show_usage() {
     (>&2 echo "ghcup-show
 Show the installed/current GHC versions
@@ -147,6 +209,10 @@ FLAGS:
     exit 1
 }
 
+# @FUNCTION: rm_usage
+# @DESCRIPTION:
+# Print the help message for 'ghcup rm' to STDERR
+# and exit the script with status code 1.
 rm_usage() {
     (>&2 echo "ghcup-rm
 Remove the given GHC version installed by ghcup
@@ -166,11 +232,22 @@ ARGS:
 
 ## utilities ##
 
+# @FUNCTION: die
+# @USAGE: [msg]
+# @DESCRIPTION:
+# Exits the shell script with status code 2
+# and prints the given message in red to STDERR, if any.
 die() {
     (>&2 red_message "$1")
     exit 2
 }
 
+# @FUNCTION: edo
+# @USAGE: <command>
+# @DESCRIPTION:
+# Executes the given command. Also prints what
+# command that is (in blue) if verbosity is enabled.
+# Exits with status code 2 if the command failed.
 edo()
 {
     if ${VERBOSE} ; then
@@ -179,6 +256,10 @@ edo()
     "$@" || exit 2
 }
 
+# @FUNCTION: debug_message
+# @USAGE: <msg>
+# @DESCRIPTION:
+# Print a blue debug message if verbosity is enabled.
 debug_message() {
     if ${VERBOSE} ; then
         printf "\\033[0;34m%s\\033[0m\\n" "$1"
@@ -189,6 +270,12 @@ debug_message() {
     fi
 }
 
+# @FUNCTION: optionv
+# @USAGE: <arg1> [arg2]
+# @DESCRIPTION:
+# If verbosity is enabled, echo the first argument, otherwise
+# the second (if any).
+# @STDOUT: first or second argument
 optionv() {
     if ${VERBOSE} ; then
         echo "$1"
@@ -199,18 +286,35 @@ optionv() {
     fi
 }
 
+# @FUNCTION: status_message
+# @USAGE: <msg>
+# @DESCRIPTION:
+# Print a green status message.
 status_message() {
     printf "\\033[0;32m%s\\033[0m\\n" "$1"
 }
 
+# @FUNCTION: warning_message
+# @USAGE: <msg>
+# @DESCRIPTION:
+# Print a yellow warning message.
 warning_message() {
     printf "\\033[1;33m%s\\033[0m\\n" "$1"
 }
 
+# @FUNCTION: red_message
+# @USAGE: <msg>
+# @DESCRIPTION:
+# Print a red message.
 red_message() {
     printf "\\033[0;31m%s\\033[0m\\n" "$1"
 }
 
+# @FUNCTION: get_distro_name
+# @DESCRIPTION:
+# Gets the current distro identifier following
+# https://unix.stackexchange.com/a/6348
+# @STDOUT: current distro identifier
 get_distro_name() {
     if [ -f /etc/os-release ]; then
         # freedesktop.org and systemd
@@ -234,6 +338,11 @@ get_distro_name() {
     fi
 }
 
+# @FUNCTION: get_distro_ver
+# @DESCRIPTION:
+# Gets the current distro version (if any) following
+# https://unix.stackexchange.com/a/6348
+# @STDOUT: current distro version, if any
 get_distro_ver() {
     if [ -f /etc/os-release ]; then
         # freedesktop.org and systemd
@@ -257,7 +366,12 @@ get_distro_ver() {
     fi
 }
 
-
+# @FUNCTION: get_arch
+# @DESCRIPTION:
+# Gets the architecture following
+# https://unix.stackexchange.com/a/6348
+# Fails for any architecture that we don't know a GHC version for.
+# @STDOUT: current architecture
 get_arch() {
     myarch=$(uname -m)