Add/update docstrings to Bash interactive mode functions

dotfiles/bash/main.bashrc

@@ -13,6 +13,14 @@ test -f /usr/share/git-core/contrib/completion/git-prompt.sh \
 ### '''' ###
 
 git() {
+    #
+    # /usr/bin/git wrapper just to disable dangerous commands
+    #
+    # In particular, `git-am` is a a close typo of my favorite
+    # aliases `ap` (`git-add --patch`) and `cm` (`git-commit`)
+    # but it's dangerous to call by accident as it destroys
+    # workdir changes.
+    #
     if grep -Fwqse "$1" "$GIT_DISABLED_COMMANDS"; then
         echo "You don't want this." >&2
         return 1
@@ -22,29 +30,55 @@ git() {
 }
 
 grepr() {
+    #
+    # Grep recursively, keeping numbers and ignoring common dirs
+    #
+    # Number one tool for refactoring!
+    #
     local p=$1; shift
     grep --color -n --exclude-dir=".git" -e "$p" -r "$@"
 }
 
 greph() {
+    #
+    # Grep through bash history
+    #
     history | sed 's/^  *//; s/  / /' | cut -d' ' -f2- | grep "$@"
 }
 
 gitcd() {
+    #
+    # Deep in git repo, cd to the git root
+    #
     cd "$(git rev-parse --show-toplevel)"
 }
 
 clsz() {
+    #
+    # Clear screen and move the prompt to bottom
+    #
     tput clear; tput cup "$(tput lines)" 0
 }
 
 bcdiff() {
+    #
+    # Call bcompare only if objects actually differ
+    #
     test $# -eq 2 && diff "$@" >/dev/null && return
     bcompare "$@" &
 }
 
 vims() {
-    # 2015-07-10 06:10:48.603953758 +0200 ~/TODO.todo
+    #
+    # Show "abandoned" Vim .swp files in a nice table
+    #
+    # Call this after crash or poweroff to get back and recover
+    # files open before the fact.  Example:
+    #
+    #     2015-07-10 06:10:48.603953758 +0200 ~/TODO.todo
+    #
+    # Depends on .swp settings defined in my mydots repo.
+    #
     local swap="$HOME/.local/share/vim/swap"
     find "$swap" -type f -print0 \
       | xargs -0 -r stat -c "%y %n" \
@@ -60,9 +94,13 @@ vims() {
 }
 
 xod() {
-    # dump xo in a file named $1 somewhere in /tmp; echo the path
+    #
+    # Like mktemp but get the content from clipboard
+    #
+    # Dump xo in a file named $1 somewhere in /tmp; echo the path
     # usage: scp $(xod useful_name.txt) eg:some/shared/place
     # instead of xo>useful_name.txt; scp useful_name.txt eg:some/shared/place; rm useful_name.txt
+    #
     local name="${1:-clipboard_dump.txt}"
     local tmp=$(mktemp -d -t "xod.XXXXXXXX")
     xclip -o > "$tmp/$name"
@@ -70,7 +108,9 @@ xod() {
 }
 
 xood() {
-    # just like xod() but using xoo
+    #
+    # Just like xod() but using xoo (i.e. 'clipboard' clipboard)
+    #
     local name="${1:-clipboard_dump.txt}"
     local tmp=$(mktemp -d -t "xood.XXXXXXXX")
     xclip -selection clipboard -o > "$tmp/$name"
@@ -78,6 +118,9 @@ xood() {
 }
 
 yum_hasbin() {
+    #
+    # Ask yum who has bin $1 (and make the output actually readable)
+    #
     local bname
     for bname in "$@";
     do