add and restore some docstrings

home/-shrc

@@ -5,7 +5,7 @@
 # {{{1 utilities
 
 if [ -z "$ZSH_VERSION" ]; then
-    has() { # hardcode this function from ~/sh/has for convenience
+    has() { ### @- hardcoded here for convenience.
         which "$1" >/dev/null 2>&1 && which "$1"
     }
 fi
@@ -21,7 +21,8 @@ else
     alias maybesudo="maybesudo_ " # allows aliases within the alias
 fi
 
-ADDPATH() {
+ADDPATH() { ### @ ADDPATH
+    ### append a directory to `$PATH` if it isn't already present.
     new="$(readlink -f "$1")"
     if [ ! -d "$new" ]; then
         echo -E "ADDPATH: path doesn't exist: $1" >&2
@@ -109,67 +110,70 @@ alias lr="lr -G"
 
 export LESS='-SRQ'
 alias db="dropbox_uploader"
-alias fils="du -bahd1"
-alias lsa="ls -A --group-directories-first"
-alias perlu='perl -Mopen=locale -Mutf8'
-alias rgn="rg --no-ignore"
-alias cms="cryptominisat5 --verb 0"
-alias curls="curl -sS"
+alias fils="du -bahd1" ### @- (GNU du) display human-friendly filesizes for the files in a directory.
+alias lsa="ls -A --group-directories-first" ### @- (GNU ls) list files with directories and dotfiles ordered first.
+alias perlu='perl -Mopen=locale -Mutf8' ### @- invoke perl expecting files with UTF-8 encoding.
+alias rgn="rg --no-ignore" ### @- invoke ripgrep without respecting `.gitignore` files.
+alias cms="cryptominisat5 --verb 0" ### @- invoke cryptominisat5 with less noise.
+alias curls="curl -sS" ### @- invoke curl with less noise.
 
 # git {{{2
 
-alias get="git clone --single-branch --depth 1"
-alias gs='git status' # rip ghostscript
-alias gd='git diff -U2'
-alias gds='git --no-pager diff --stat'
-alias gl='git log --oneline'
-alias glo='git log --graph --decorate --pretty=oneline --abbrev-commit --all'
-alias g1='git log --pretty=oneline --abbrev-commit --color=always | head -1'
-alias gr='git remote -v'
-alias gb='git --no-pager branch'
+alias get="git clone --single-branch --depth 1" ### @- retrieve the most recent files from the default branch of a git repository, and not much else.
+alias gs='git status' ### @- invoke git's status subcommand.
+alias gd='git diff -U2' ### @- invoke git's diff subcommand with fewer lines of context.
+alias gds='git --no-pager diff --stat' ### @- display difference stats from git.
+alias gl='git log --oneline' ### @- invoke git's log subcommand with a single line per commit.
+alias glo='git log --graph --decorate --pretty=oneline --abbrev-commit --all' ### @- navigate git's commit tree succinctly.
+alias g1='git log --pretty=oneline --abbrev-commit --color=always | head -1' ### @- display the most recent git commit.
+alias gr='git remote -v' ### @- display remote git repositories verbosely.
+alias gb='git --no-pager branch' ### @- display the current git branch.
 
 # being specific {{{2
 
 [ -e "$HOME/python3" ] && alias py="~/python3" || alias py="python3"
 alias pip="maybesudo -H pip3"
-alias revend='objcopy -I binary -O binary --reverse-bytes=4'
+alias revend='objcopy -I binary -O binary --reverse-bytes=4' ### @- reverse the 4-byte endianness of a single file. *this is an in-place operation!*
 alias aur="BUILDDIR=$HOME/src $HOME/sh/aur -jj"
-alias clone='maybesudo rsync -aHA --info=progress2 --no-i-r'
-alias aligntabs="column -t -s$'\t'"
-alias crawla='ssh [email protected] -i ~/.ssh/crawl'
-alias crawlz='ssh [email protected] -i ~/.ssh/crawl'
+alias clone='maybesudo rsync -aHA --info=progress2 --no-i-r' ### @- invoke rsync suitably for creating virtually indistinguishable copies of files.
+alias aligntabs="column -t -s$'\t'" ### @- align tab-delimited fields in stdin.
+alias crawla='ssh [email protected] -i ~/.ssh/crawl' ### @- play Dungeon Crawl: Stone Soup through ssh on the akrasiac server.
+alias crawlz='ssh [email protected] -i ~/.ssh/crawl' ### @- play Dungeon Crawl: Stone Soup through ssh on the develz server.
 
 alias ll="lol" # workaround for a strange issue with bash
-lol() {
+lol() { ### @ ll - list files verbosely, fancily, ordered, but not recursively.
     { lr -1lshGG -o tev -t 'name~~".*"||type==d' "$@" \
      && lr -1lshGG -o tev -t 'name!~~".*"&&type!=d' "$@" \
      || ls -lAX --group-directories-first --color=force "$@"; } | less
 }
 
 # providing extra functionality {{{2
 
-alias diff="git diff --color=auto --no-ext-diff --no-index --no-prefix"
-alias gc="git column --mode=dense --padding=2"
-alias counts='find . | wc -l'
-alias exts="find -type f | grep -o '\\.[^/.]*$' | sort | uniq -c | sort -n"
-alias nocom='grep -Ev --line-buffered --color=never "^[[:space:]]*(//|#)"'
-alias sortip="sort -t . -k 1,1n -k 2,2n -k 3,3n -k 4,4n"
-alias jrep='grep -aPo "[\x{20}-\x{7E}\x{4E00}-\x{9FFF}\x{3040}-\x{30FF}]+"'
-alias bomb='uconv -f utf-8 -t utf-8 --add-signature'
-alias cleanse='tr -cd "\11\12\15\40-\176"'
-alias rot13='tr "A-Za-z0-9" "N-ZA-Mn-za-m5-90-4"'
-alias unwrap='awk '\''BEGIN{RS="\n\n";FS="\n"}{for(i=1;i<=NF;i++)printf "%s ",$i;print "\n"}'\'
-alias double='awk "{print;print}"'
-alias join2='paste -d" " - -'
-alias katagana='perlu -MUnicode::Normalize -pe'"'"'$_=NFKD($_)=~y/ァ-ヶ /ぁ-ゖ　/r'"'"
-alias picky='{ pacman -Qgq base base-devel xorg xorg-drivers xfce4 | double; pacman -Qeq; } | sort | uniq -u'
-alias unused='{ pacman -Qtq; pacman -Qeq | double; } | sort | uniq -u'
-alias makepkgf='makepkg -Af --skipchecksums --skippgpcheck'
-alias rakef='rake && gem build *.gemspec && gem install *.gem'
-
-eashare() {
-    # NOTE: this only works on MSYS2 for now.
-    # NOTE: i lied, this doesn't work anymore. idk
+alias diff="git diff --color=auto --no-ext-diff --no-index --no-prefix" ### @- use git's diff subcommand for general diffing.
+alias gc="git column --mode=dense --padding=2" ### @- columnize text by using git's column subcommand.
+alias counts='find . | wc -l' ### @- count files in the current directory, including files found recursively.
+alias exts="find -type f | grep -o '\\.[^/.]*$' | sort | uniq -c | sort -n" ### @- count and sort file extensions in the current directory, including files found recursively.
+alias nocom='grep -Ev --line-buffered --color=never "^[[:space:]]*(//|#)"' ### @- strip single-line C-like and shell-like comments.
+alias sortip="sort -t . -k 1,1n -k 2,2n -k 3,3n -k 4,4n" ### @- sort numerically by IPv4 segments.
+alias jrep='grep -aPo "[\x{20}-\x{7E}\x{4E00}-\x{9FFF}\x{3040}-\x{30FF}]+"' ### @- extract strings comprised of basic ASCII or Japanese codepoints.
+alias bomb='uconv -f utf-8 -t utf-8 --add-signature' ### @- add a Byte-Order Mark to a file.
+alias cleanse='tr -cd "\11\12\15\40-\176"' ### @- strip unprintable and non-ASCII characters.
+alias rot13='tr "A-Za-z0-9" "N-ZA-Mn-za-m5-90-4"' ### @- rot13 with numbers rotated as well.
+alias unwrap='awk '\''BEGIN{RS="\n\n";FS="\n"}{for(i=1;i<=NF;i++)printf "%s ",$i;print "\n"}'\' ### @- join paragraphs into one line each.
+alias double='awk "{print;print}"' ### @- print every line twice. <br/> print every line twice.
+alias join2='paste -d" " - -' ### @- join every other line.
+alias katagana='perlu -MUnicode::Normalize -pe'"'"'$_=NFKD($_)=~y/ァ-ヶ /ぁ-ゖ　/r'"'" ### @- convert katakana codepoints to their equivalent hiragana.
+### useful for translating [debug text from ancient games.](https://tcrf.net/)
+alias picky='{ pacman -Qgq base base-devel xorg xorg-drivers xfce4 | double; pacman -Qeq; } | sort | uniq -u' ### @- TODO
+alias unused='{ pacman -Qtq; pacman -Qeq | double; } | sort | uniq -u' ### @- TODO
+alias makepkgf='makepkg -Af --skipchecksums --skippgpcheck' ### @- make the freakin' package!
+alias rakef='rake && gem build *.gemspec && gem install *.gem' ### @- make the freakin' gem!
+
+eashare() { ### @- upload a file and copy its URL to the clipboard.
+    ###
+    ### **NOTE:** this only works on MSYS2 for now.
+    ###
+    ### **NOTE:** i lied, this doesn't work at all.
     local dest="${1##*/}"
     eaput "$1" || return 1
     printf "%s" "$_REMOTE_DOMAIN/$_REMOTE_DIR/$dest" >> /dev/clipboard

home/bashrc

@@ -46,5 +46,4 @@ ADDPATH "$HOME/sh"
 . ~/.sh-bash
 : $((SOURCING-=1))
 
-# TODO: respect initctl like in .zshrc.
-alias reload='cd; exec bash'
+alias reload='cd; exec bash' ### @- **TODO:** respect initctl like in `.zshrc`.

home/zshrc

@@ -68,22 +68,30 @@ function {
 
 local fuzzy=`has fzy || print`
 
-dirprev() {
+dirprev() { ### @ dirprev
+    ### rotate and change to the previous directory in the directory stack
+    ### without consuming the prompt.
     pushd -q +1
     zle reset-prompt
     precmd
 }
-dirnext() {
+dirnext() { ### @ dirnext
+    ### rotate and change to the next directory in the directory stack
+    ### without consuming the prompt.
     pushd -q -0
     zle reset-prompt
     precmd
 }
-dirup() {
+dirup() { ### @ dirup
+    ### change to the parent directory of the current working directory
+    ### without consuming the prompt.
     cd ..
     zle reset-prompt
     precmd
 }
-dirview() {
+dirview() { ### @ dirview
+    ### use a fuzzy finder to select a recent directory in the directory stack
+    ### and change to it without consuming the prompt.
     print
     if [ -n "$fuzzy" ]; then
         local d="$(dirs -pl | awk '!seen[$0]++' | "$fuzzy")"
@@ -155,21 +163,26 @@ bindkey '^Xe' edit-command-line # ctrl+x -> e
 
 . ~/.-shrc
 
-alias -g OMFG="1>/dev/null"
-alias -g STFU="2>/dev/null"
-alias -g WHOA='${whoa[@]}'
-alias -g WELP='${welp[@]}'
+alias -g OMFG="1>/dev/null" ### @ OMFG - silence stdout.
+alias -g STFU="2>/dev/null" ### @ STFU - silence stderr.
+alias -g WHOA='${whoa[@]}' ### @ WHOA - expand to several C/C++ flags to ease development.
+alias -g WELP='${welp[@]}' ### @ WELP - expand to C++ flags to enable a C++-as-C facade.
 
 alias sc="~/sh/sc" # only runs in bash (for now), so be explicit with path
-alias pl="print -l" # not in -shrc because this only makes sense with zsh
+# not in -shrc because this only makes sense with zsh:
+alias pl="print -l" ### @ pl - print each argument on its own line.
 
-function tw() { # needs the "function" keyword or else zsh complains
+# needs the "function" keyword or else zsh complains:
+function tw() { ### @ tw
+    ### invoke `twitch` as a job with both stdout and stderr silenced.
     twitch "$@" OMFG STFU &
 }
 
 local host="${(L)HOST}"
 
 function {
+    # initialize prompts.
+
     local t="${TERM%%-*}"
     if [ "$t" = xterm ] || [ "$t" = screen ] || [ "$t" = tmux ]; then
         # set window title
@@ -204,7 +217,9 @@ function {
     PROMPT="%{$reset${s}%(?.${good}.${bad})${e}${s}97${e}%}%#%{$reset%} "
 }
 
-reload() {
+reload() { ### @ reload
+    ### reload zsh by wiping temp files, recompiling rc files,
+    ### and replacing the current process with a new zsh process.
     # initctl has a "reload" symlink, but i'm already too used to typing this.
     # to remedy this, when args are passed, invoke initctl instead.
     if [ $# -gt 0 ]; then
@@ -229,6 +244,7 @@ reload() {
 
 # generated by dircolors with https://github.com/isene/LS_COLORS
 function {
+    # initialize colors for ls.
     local lsc= line=
     < ~/.ls_colors | tr -d $'\r' | while read -r line; do
         lsc+="$line:"

sh/arith

@@ -6,7 +6,8 @@
 # though technically compatible with other shells,
 # extra functionality is through zsh's extended arithmetic functions.
 
-arith() {
+arith() { ### @-
+    ### perform arithmetic using the shell and display the result.
 #   <<<"$(($@))"
     printf "%s\n" "$(($@))"
 }

sh/aur

@@ -4,7 +4,10 @@
 
 # TODO: check compatibility with bash and dash.
 
-aur() {
+aur() { ### @-
+    ### download, edit, make, and install packages from the
+    ### [AUR.](https://aur.archlinux.org/)
+    ### it's a little broken.
     trap 'exit 1' SIGINT SIGTERM
 
     local bd="${BUILDDIR:-$PWD}"

sh/autosync

@@ -5,7 +5,9 @@
 
 # TODO: portable way of dodging aliases to allow other shell support?
 
-autosync() {
+autosync() { ### @-
+    ### combine `inotifywait` and `rsync`.
+    ### this is sometimes nicer than `ssh`-ing into a server and running `vim` remotely.
     target="$1"
     shift
     # as a reminder not to get the argument order mixed up:

sh/cdbusiest

@@ -1,7 +1,8 @@
 #!/usr/bin/env zsh
 # YES_ZSH
 
-cdbusiest() {
+cdbusiest() { ### @-
+    ### cd to the directory with the most files in it, counted recursively.
     dbusiest | read -r c d
     [ -z $c ] && return 1
     printf "%s\n" "$c $d"

sh/colors

@@ -3,7 +3,9 @@
 # YES_BASH
 # NO_DASH
 
-colors() {
+colors() { ### @-
+    ### print out all the foreground and background terminal color combinations.
+    ### excluding boilerplate, this script is a mere a 76-characters long!
     [ $# -eq 0 ] || { printf "%s\n" "$0: does not take arguments" >&2; return 1; }
     printf "\e[%dm$(printf " \e[%dm mV \e[40m" {4,10}{0..7})\e[0m\n" {3,9}{0..7}
 }

sh/compandy

@@ -2,7 +2,9 @@
 # script to make sense of compand's parameters
 # YES_ZSH
 
-compandy() {
+compandy() { ### @-
+    ### generate compand arguments for ffmpeg audio filters.
+    ### this is kinda pointless now that acompressor is wildly supported.
     if [ $# -eq 0 ]; then
         echo -E "usage: $0 {threshold} {ratio} [attack] [release] [knee] [gain] [delay]"
         return 1

sh/compile

@@ -4,7 +4,7 @@
 # NO_DASH
 
 # I'll just leave this here...
-__setup_clang_ubuntu() {
+__setup_clang_ubuntu() { ### @-
     local site="http://apt.llvm.org"
     local name="$(lsb_release -c | cut -f2)"
     local version=10 # NOTE: no longer decimal-based
@@ -26,7 +26,20 @@ deb $site/$name/ llvm-toolchain-$name-$version main\n\
     echo update-alternatives --install /usr/bin/llvm-symbolizer llvm-symbolizer /usr/bin/llvm-symbolizer-$version $priority
 }
 
-compile() {
+compile() { ### @-
+    ### compile single-file C and C++ programs, messily.
+    ###
+    ### supports gcc and clang on \*nix, and mingw64 gcc, msvc clang,
+    ### and regular msvc on Windows. tested on x86\_64 and on ARMv7 as well.
+    ### does not support MacOS, maybe someday…
+    ###
+    ### defaults to gnu11 and gnu++1z as C and C++ standards respectively.
+    ### defaults to clang, gcc, and msvc in that order.
+    ###
+    ### `compile` attempts to guess the most sane switches for any program, so that compilation may reduce to:
+    ###
+    ### **TODO:** restore examples.
+
     # FIXME: compile gcc portrend.c -lsdl
     # this causes mayhem!
 

sh/confirm

@@ -3,6 +3,17 @@
 # YES_BASH
 # NO_DASH
 
+### @ confirm
+### display a simple yes-or-no prompt and return 0-or-1 respectively.
+###
+### ```
+### $ confirm && echo yay || echo nay
+### Continue? [y/N] y
+### yay
+### $ confirm && echo yay || echo nay
+### Continue? [y/N] n
+### nay
+### ```
 if [ -n "$ZSH_VERSION" ]; then
     confirm() {
         [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }

sh/days

@@ -3,7 +3,13 @@
 # YES_BASH
 # YES_DASH
 
-days() {
+days() { ### @-
+    ### compute days since a given date.
+    ###
+    ### ```
+    ### $ days 'January 1 1970'
+    ### 18838
+    ### ```
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     echo $(( ($(date +%s) - $(date -d "$1" +%s)) / 60 / 60 / 24 ))
 }

sh/dbusiest

@@ -3,7 +3,8 @@
 # NO_BASH
 # NO_DASH
 
-dbusiest() {
+dbusiest() { ### @-
+    ### display the directory with the most files in it, counted recursively.
     [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     local c d
     for d in *(FDN); do

sh/dfu

@@ -3,7 +3,10 @@
 # YES_BASH
 # YES_DASH
 
-dfu() {
+dfu() { ### @-
+    ### pretty-print `df` in GiB.
+    ###
+    ### **TODO:** restore examples.
     [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     df -xtmpfs | awk '
     NR==1{printf"%-20s %7s %7s %7s %7s\n","Filesystem","Used","Max","Left","Misc"}

sh/disf

@@ -6,7 +6,8 @@
 
 # TODO: actually test that this works with dash.
 
-function disf() {
+function disf() { ### @-
+    ### disassemble a single function from an unstripped executable, unreliably.
     [ $# -le 2 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     local exe="${1:?first argument should be an unstripped executable}"
     local symbol="${2:?second argument should be a function name}"