Fix, complete and add docstring documentation to builtin commands

Level out the builtin commands loaded at startup in terms of format and
expressiveness. The following convention was followed:
* commands that take more than one argument have to be described along
  with their parameters prior to the actual documentation, otherwise the
  docstring consists in a capitalized sentence
  e.g. `command <arg1>: do something`
* optional arguments are enclosed in square brackets, to comply with the
  format used for hardcoded commands
  e.g. `cd [<directory>]`
* describe the effects of the command in the documentation string and
  omit implementation details unless they are relevant. Usually command
  names include the name of the tool they use, so they don't need to be
  redundantly mentioned
  e.g. `tmux-new-pane <arguments>: open a new pane`
* document the format the parameters to the commands, or list them if
  they are to be chosen among a list of static values (c.f. `spell.kak`)

rc/base/autowrap.kak

@@ -38,7 +38,7 @@ def -hidden autowrap-cursor %{ eval -save-regs '/"|^@m' %{
     }
 } }
 
-def autowrap-enable -docstring "Wrap the lines in which characters are inserted" %{
+def autowrap-enable -docstring "Automatically wrap the lines in which characters are inserted" %{
     hook -group autowrap window InsertChar [^\n] autowrap-cursor
 }
 

rc/base/ctags.kak

@@ -5,7 +5,7 @@
 
 decl str-list ctagsfiles 'tags'
 
-def -params 0..1 \
+def -params ..1 \
     -shell-candidates '
         ( for tags in $(printf %s\\n "${kak_opt_ctagsfiles}" | tr \':\' \'\n\'); do
               namecache=$(dirname ${tags})/.kak.$(basename ${tags}).namecache
@@ -14,7 +14,8 @@ def -params 0..1 \
               fi
               cat ${namecache}
           done )' \
-    -docstring 'Jump to tag definition' \
+    -docstring %{tag [<symbol>]: jump to a symbol's definition
+If no symbol is passed then the current selection is used as symbol name} \
     tag \
     %{ %sh{
         export tagname=${1:-${kak_selection}}

rc/base/spell.kak

@@ -1,7 +1,13 @@
 decl -hidden range-faces spell_regions
 decl -hidden str spell_tmp_file
 
-def -params ..1 spell -docstring "Check spelling of the current buffer with aspell (the first optional argument is the language against which the check will be performed)" %{
+def -params ..1 \
+    -docstring %{spell [<language>]: spell check the current buffer
+The first optional argument is the language against which the check will be performed
+Formats of language supported:
+ - ISO language code, e.g. 'en'
+ - language code above followed by a dash or underscore with an ISO country code, e.g. 'en-US'} \
+    spell %{
     try %{ addhl ranges 'spell_regions' }
     %sh{
         file=$(mktemp -d -t kak-spell.XXXXXXXX)/buffer

rc/base/tmux.kak

@@ -28,24 +28,23 @@ def -hidden -params 1.. tmux-new-impl %{
     }
 }
 
-def tmux-new-vertical -params .. -command-completion -docstring "Create a new vertical pane in tmux" %{
+def tmux-new-vertical -params .. -command-completion -docstring "Create a new vertical pane" %{
     tmux-new-impl 'split-window -v' %arg{@}
 }
 
-def tmux-new-horizontal -params .. -command-completion -docstring "Create a new horizontal pane in tmux" %{
+def tmux-new-horizontal -params .. -command-completion -docstring "Create a new horizontal pane" %{
     tmux-new-impl 'split-window -h' %arg{@}
 }
 
-def tmux-new-window -params .. -command-completion -docstring "Create a new window in tmux" %{
+def tmux-new-window -params .. -command-completion -docstring "Create a new window" %{
     tmux-new-impl 'new-window' %arg{@}
 }
 
-def -docstring "focus given client" \
-    -params 0..1 -client-completion \
+def -docstring %{tmux-focus [<client>]: focus the given client
+If no client is passed then the current one is used} \
+    -params ..1 -client-completion \
     tmux-focus %{ %sh{
-    if [ $# -gt 1 ]; then
-        echo "echo -color Error 'too many arguments, use focus [client]'"
-    elif [ $# -eq 1 ]; then
+    if [ $# -eq 1 ]; then
         printf %s\\n "eval -client '$1' focus"
     elif [ -n "${kak_client_env_TMUX}" ]; then
         TMUX="${kak_client_env_TMUX}" tmux select-pane -t "${kak_client_env_TMUX_PANE}" > /dev/null

rc/base/x11.kak

@@ -18,7 +18,8 @@ decl str termcmd %sh{
     done
 }
 
-def -docstring 'create a new kak client for current session' \
+def -docstring %{x11-new [<command>]: create a new kak client for the current session
+The optional arguments will be passed as arguments to the new client} \
     -params .. \
     -command-completion \
     x11-new %{ %sh{
@@ -30,12 +31,11 @@ def -docstring 'create a new kak client for current session' \
         setsid ${kak_opt_termcmd} "kak -c ${kak_session} ${kakoune_params}" < /dev/null > /dev/null 2>&1 &
 }}
 
-def -docstring 'focus given client\'s window' \
-    -params 0..1 -client-completion \
+def -docstring %{x11-focus [<client>]: focus a given client's window
+If no client is passed, then the current client is used} \
+    -params ..1 -client-completion \
     x11-focus %{ %sh{
-        if [ $# -gt 1 ]; then
-            echo "echo -color Error 'too many arguments, use focus [client]'"
-        elif [ $# -eq 1 ]; then
+        if [ $# -eq 1 ]; then
             printf %s\\n "eval -client '$1' focus"
         else
             xdotool windowactivate $kak_client_env_WINDOWID > /dev/null

rc/core/doc.kak

@@ -34,7 +34,8 @@ def -params 1..2 \
             printf %s\\n "${l%.*}"
         done
     } \
-    doc -docstring "Open a buffer containing the documentation about a given subject" %{
+    doc -docstring %{doc <topic> [<keyword>]: open a buffer containing documentation about a given topic
+An optional keyword argument can be passed to the function, which will be automatically selected in the documentation} %{
     %sh{
         readonly PATH_DOC="${kak_runtime}/../doc/kak/manpages/${1}.gz"
 

rc/core/formatter.kak

@@ -1,5 +1,5 @@
 decl str formatcmd ""
-def format -docstring "Format the entire buffer with an external utility" %{
+def format -docstring "Format the contents of the current buffer" %{
     %sh{
         if [ ! -z "${kak_opt_formatcmd}" ]; then
             readonly kak_opt_formatcmd=$(printf '%s' "${kak_opt_formatcmd}" | sed 's/ /<space>/g')

rc/core/grep.kak

@@ -3,7 +3,9 @@ decl str toolsclient
 decl -hidden int _grep_current_line 0
 
 def -params .. -file-completion \
-    grep -docstring "Grep utility wrapper" %{ %sh{
+    -docstring %{grep [<arguments>]: grep utility wrapper
+All the optional arguments are forwarded to the grep utility} \
+    grep %{ %sh{
      output=$(mktemp -d -t kak-grep.XXXXXXXX)/fifo
      mkfifo ${output}
      if [ $# -gt 0 ]; then
@@ -41,7 +43,7 @@ hook global WinSetOption filetype=(?!grep).* %{
 
 decl str jumpclient
 
-def grep-jump %{
+def -hidden grep-jump %{
     eval -collapse-jumps %{
         try %{
             exec 'xs^((?:\w:)?[^:]+):(\d+):(\d+)?<ret>'
@@ -52,7 +54,7 @@ def grep-jump %{
     }
 }
 
-def grep-next -docstring 'Jump to next grep match' %{
+def grep-next -docstring 'Jump to the next grep match' %{
     eval -collapse-jumps -try-client %opt{jumpclient} %{
         buffer '*grep*'
         exec "%opt{_grep_current_line}g<a-l>/^[^:]+:\d+:<ret>"
@@ -61,7 +63,7 @@ def grep-next -docstring 'Jump to next grep match' %{
     try %{ eval -client %opt{toolsclient} %{ exec %opt{_grep_current_line}g } }
 }
 
-def grep-prev -docstring 'Jump to previous grep match' %{
+def grep-prev -docstring 'Jump to the previous grep match' %{
     eval -collapse-jumps -try-client %opt{jumpclient} %{
         buffer '*grep*'
         exec "%opt{_grep_current_line}g<a-/>^[^:]+:\d+:<ret>"

rc/core/make.kak

@@ -2,7 +2,10 @@ decl str makecmd make
 decl str toolsclient
 decl -hidden int _make_current_error_line
 
-def -params .. make -docstring "Make utility wrapper" %{ %sh{
+def -params .. \
+    -docstring %{make [<arguments>]: make utility wrapper
+All the optional arguments are forwarded to the make utility} \
+    make %{ %sh{
      output=$(mktemp -d -t kak-make.XXXXXXXX)/fifo
      mkfifo ${output}
      ( eval ${kak_opt_makecmd} "$@" > ${output} 2>&1 ) > /dev/null 2>&1 < /dev/null &
@@ -36,7 +39,7 @@ hook global WinSetOption filetype=(?!make).* %{
 
 decl str jumpclient
 
-def make-jump -docstring 'Jump to error location' %{
+def -hidden make-jump %{
     eval -collapse-jumps %{
         try %{
             exec gl<a-?> "Entering directory" <ret>
@@ -53,7 +56,7 @@ def make-jump -docstring 'Jump to error location' %{
     }
 }
 
-def make-next -docstring 'Jump to next error' %{
+def make-next -docstring 'Jump to the next make error' %{
     eval -collapse-jumps -try-client %opt{jumpclient} %{
         buffer '*make*'
         exec "%opt{_make_current_error_line}g<a-l>/[0-9]+: (?:fatal )?error:<ret>"
@@ -62,7 +65,7 @@ def make-next -docstring 'Jump to next error' %{
     try %{ eval -client %opt{toolsclient} %{ exec %opt{_make_current_error_line}g } }
 }
 
-def make-prev -docstring 'Jump to previous error' %{
+def make-prev -docstring 'Jump to the previous make error' %{
     eval -collapse-jumps -try-client %opt{jumpclient} %{
         buffer '*make*'
         exec "%opt{_make_current_error_line}g<a-h><a-/>[0-9]+: (?:fatal )?error:<ret>"

rc/core/man.kak

@@ -47,7 +47,7 @@ def -hidden -params 1..2 _man %{ %sh{
     fi
 } }
 
-def -params .. \
+def -params ..1 \
   -shell-completion %{
     prefix=$(printf %s\\n "$1" | cut -c1-${kak_pos_in_token} 2>/dev/null)
     for page in /usr/share/man/*/${prefix}*.[1-8]*; do
@@ -59,7 +59,10 @@ def -params .. \
         esac
     done
   } \
-  man -docstring "Manpages viewer wrapper" %{ %sh{
+  -docstring %{man [<page>]: manpage viewer wrapper
+If no argument is passed to the command, the selection will be used as page
+The page can be a word, or a word directly followed by a section number between parenthesis, e.g. kak(1)} \
+    man %{ %sh{
     subject=${@-$kak_selection}
 
     ## The completion suggestions display the page number, strip them if present

rc/extra/clang.kak

@@ -5,7 +5,10 @@ decl -hidden completions clang_completions
 decl -hidden line-flags clang_flags
 decl -hidden str clang_errors
 
-def clang-parse -params 0..1 -docstring "Parse the contents of the current buffer with clang" %{
+def -params ..1 \
+    -docstring %{Parse the contents of the current buffer
+The syntaxic errors detected during parsing are shown when auto-diagnostics are enabled} \
+    clang-parse %{
     %sh{
         dir=$(mktemp -d -t kak-clang.XXXXXXXX)
         mkfifo ${dir}/fifo
@@ -95,7 +98,7 @@ def clang-parse -params 0..1 -docstring "Parse the contents of the current buffe
     }
 }
 
-def clang-complete -docstring "Complete the current selection with clang" %{ clang-parse -complete }
+def clang-complete -docstring "Complete the current selection" %{ clang-parse -complete }
 
 def -hidden clang-show-completion-info %[ try %[
     eval -draft %[
@@ -108,7 +111,7 @@ def -hidden clang-show-completion-info %[ try %[
     ] ]
 ] ]
 
-def clang-enable-autocomplete -docstring "Enable completion with clang" %{
+def clang-enable-autocomplete -docstring "Enable automatic clang completion" %{
     set window completers "option=clang_completions:%opt{completers}"
     hook window -group clang-autocomplete InsertIdle .* %{
         try %{
@@ -134,13 +137,15 @@ def -hidden clang-show-error-info %{ %sh{
     fi
 } }
 
-def clang-enable-diagnostics -docstring "Activate automatic diagnostics of the code by clang" %{
+def clang-enable-diagnostics -docstring %{Activate automatic error reporting and diagnostics
+Information about the analysis are showned after the buffer has been parsed with the clang-parse function} \
+%{
     addhl flag_lines default clang_flags
     hook window -group clang-diagnostics NormalIdle .* %{ clang-show-error-info }
     hook window -group clang-diagnostics WinSetOption ^clang_errors=.* %{ info; clang-show-error-info }
 }
 
-def clang-disable-diagnostics -docstring "Disable automatic diagnostics of the code" %{
+def clang-disable-diagnostics -docstring "Disable automatic error reporting and diagnostics" %{
     rmhl hlflags_clang_flags
     rmhooks window clang-diagnostics
 }

rc/extra/flake8.kak

@@ -3,7 +3,7 @@ decl -hidden str flake8_tmp_dir
 decl -hidden line-flags flake8_flags
 decl -hidden str flake8_errors
 
-def flake8-lint -params 0..1 -docstring "Lint the contents of the current buffer with flake8" %{
+def flake8-lint -docstring "Lint the contents of the current buffer" %{
     %sh{
         dir=$(mktemp -d -t kak-flake8.XXXXXXXX)
         mkfifo ${dir}/fifo
@@ -50,7 +50,7 @@ def -hidden flake8-show-error-info %{ %sh{
     fi
 } }
 
-def flake8-enable-diagnostics -docstring "Activate automatic diagnostics of the code by flake8" %{
+def flake8-enable-diagnostics -docstring "Activate automatic diagnostics of the code" %{
     addhl flag_lines default flake8_flags
     hook window -group flake8-diagnostics NormalIdle .* %{ flake8-show-error-info }
 }

rc/extra/git-tools.kak

@@ -22,7 +22,9 @@ decl line-flags git_diff_flags
 face GitBlame default,magenta
 
 def -params 1.. \
-  -docstring %sh{printf '%%{Git wrapping helper\navailable commands:\n add\n rm\n blame\n commit\n checkout\n diff\n hide-blame\n log\n show\n show-diff\n status\n update-diff}'} \
+  -docstring %sh{printf '%%{git [<arguments>]: git wrapping helper
+All the optional arguments are forwarded to the git utility
+Available commands:\n-add\n-rm\n-blame\n-commit\n-checkout\n-diff\n-hide-blame\n-log\n-show\n-show-diff\n-status\n-update-diff}'} \
   -shell-candidates %{
     [ $kak_token_to_complete -eq 0 ] &&
         printf "add\nrm\nblame\ncommit\ncheckout\ndiff\nhide-blame\nlog\nshow\nshow-diff\nstatus\nupdate-diff\n"

rc/extra/iterm.kak

@@ -32,15 +32,18 @@ def -hidden -params 1.. iterm-new-split-impl %{
     }
 }
 
-def iterm-new-vertical -params .. -command-completion -docstring "Create a new vertical pane in iTerm" %{
+def iterm-new-vertical -params .. -command-completion -docstring "Create a new vertical pane" %{
     iterm-new-split-impl 'vertically' %arg{@}
 }
 
-def iterm-new-horizontal -params .. -command-completion -docstring "Create a new horizontal pane in iTerm" %{
+def iterm-new-horizontal -params .. -command-completion -docstring "Create a new horizontal pane" %{
     iterm-new-split-impl 'horizontally' %arg{@}
 }
 
-def iterm-new-tab -params .. -command-completion -docstring "Create a new tab in iTerm" %{
+def -params .. -command-completion \
+    -docstring %{iterm-new-tab [<arguments>]: create a new tab
+All optional arguments are forwarded to the new kak client} \
+    iterm-new-tab %{
     %sh{
         if [ $# -gt 0 ]; then kakoune_params="-e '$@'"; fi
         sh_cmd="kak -c ${kak_session} ${kakoune_params}"
@@ -55,7 +58,10 @@ def iterm-new-tab -params .. -command-completion -docstring "Create a new tab in
     }
 }
 
-def iterm-new-window -params .. -command-completion -docstring "Create a new iTerm window" %{
+def -params .. -command-completion \
+    -docstring %{iterm-new-window [<arguments>]: create a new window
+All optional arguments are forwarded to the new kak client} \
+    iterm-new-window %{
     %sh{
         if [ $# -gt 0 ]; then kakoune_params="-e '$@'"; fi
         sh_cmd="kak -c ${kak_session} ${kakoune_params}"
@@ -69,7 +75,10 @@ def iterm-new-window -params .. -command-completion -docstring "Create a new iTe
     }
 }
 
-def iterm-focus -params 0..1 -client-completion -docstring "Focus the given client in iTerm" %{
+def -params ..1 -client-completion \
+    -docstring %{iterm-focus [<client>]: focus the given client
+If no client is passed then the current one is used} \
+    iterm-focus %{
     # Should be possible using ${kak_client_env_ITERM_SESSION_ID}.
      %sh{echo "echo -color Error 'Not implemented yet for iTerm'"}
 }

rc/extra/jedi.kak

@@ -2,7 +2,7 @@ decl -hidden str jedi_tmp_dir
 decl -hidden completions jedi_completions
 decl str-list jedi_python_path ''
 
-def jedi-complete -docstring "Complete the current selection with jedi" %{
+def jedi-complete -docstring "Complete the current selection" %{
     %sh{
         dir=$(mktemp -d -t kak-jedi.XXXXXXXX)
         mkfifo ${dir}/fifo

rc/extra/modeline.kak

@@ -100,7 +100,7 @@ def -hidden _modeline-parse %{
 
 # Add the following function to a hook on BufOpen to automatically parse modelines
 # Select the first and last `modelines` lines in the buffer, only keep modelines
-def modeline-parse %{
+def modeline-parse -docstring "Read and interpret vi-format modelines at the beginning/end of the buffer" %{
     try %{ eval -draft %{
         exec \%s\`|.\'<ret> %opt{modelines}k <a-x> %opt{modelines}X \
              s^[^\s]+?\s(vim?|kak(oune)?):\s?[^\n]+<ret>

rc/extra/ranger.kak

@@ -2,16 +2,18 @@
 # ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
 
 def ranger-open-on-edit-directory \
-    -docstring 'fallback on ranger when trying to open a directory' %{
+    -docstring 'Start the ranger file system explorer when trying to edit a directory' %{
         hook global RuntimeError "\d+:\d+: '\w+' (.*): is a directory" %{ %sh{
           directory=$(expr $kak_hook_param : "[0-9]*:[0-9]*: '[a-z]*' \\(.*\\): is a directory")
           echo ranger $directory
     }}
 }
 
-def ranger -docstring 'ranger file manager' \
-           -params ..                       \
-           -file-completion %{ %sh{
+def \
+  -params .. -file-completion \
+  -docstring %{ranger [<arguments>]: open the file system explorer to select buffers to open
+All the optional arguments are forwarded to the ranger utility} \
+  ranger %{ %sh{
   if [ -n "$TMUX" ]; then
     tmux split-window -h \
       ranger $@ --cmd " \

rc/extra/tmux-repl.kak

@@ -37,19 +37,19 @@ def -hidden -params 1..2 tmux-repl-impl %{
     }
 }
 
-def tmux-repl-vertical -params 0..1 -command-completion -docstring "Create a new vertical pane in tmux for repl interaction" %{
+def tmux-repl-vertical -params 0..1 -command-completion -docstring "Create a new vertical pane for repl interaction" %{
     tmux-repl-impl 'split-window -v' %arg{@}
 }
 
-def tmux-repl-horizontal -params 0..1 -command-completion -docstring "Create a new horizontal pane in tmux for repl interaction" %{
+def tmux-repl-horizontal -params 0..1 -command-completion -docstring "Create a new horizontal pane for repl interaction" %{
     tmux-repl-impl 'split-window -h' %arg{@}
 }
 
-def tmux-repl-window -params 0..1 -command-completion -docstring "Create a new window in tmux for repl interaction" %{
+def tmux-repl-window -params 0..1 -command-completion -docstring "Create a new window for repl interaction" %{
     tmux-repl-impl 'new-window' %arg{@}
 }
 
-def -hidden _tmux-send-text -docstring "Send selected text to the repl pane in tmux" %{
+def -hidden _tmux-send-text -docstring "Send the selected text to the repl pane" %{
     nop %sh{
         tmux set-buffer -b kak_selection "${kak_selection}"
         kak_orig_window=$(tmux display-message -p '#I')

rc/extra/x11-repl.kak

@@ -1,17 +1,18 @@
 # termcmd should already be set in x11.kak
-def -docstring 'create a new window for repl interaction' \
-    -params 0..1 \
+def -docstring %{x11-repl [<arguments>]: create a new window for repl interaction
+All optional parameters are forwarded to the new window} \
+    -params .. \
     -command-completion \
     x11-repl %{ %sh{
         if [ -z "${kak_opt_termcmd}" ]; then
            echo "echo -color Error 'termcmd option is not set'"
            exit
         fi
-        if [ $# -eq 0 ]; then cmd="bash"; else cmd="$1"; fi
+        if [ $# -eq 0 ]; then cmd="bash"; else cmd="$@"; fi
         setsid ${kak_opt_termcmd} ${cmd} -t kak_repl_window < /dev/null > /dev/null 2>&1 &
 }}
 
-def x11-send-text -docstring "send selected text to the repl window" %{
+def x11-send-text -docstring "send the selected text to the repl window" %{
     nop %sh{
         printf %s\\n "${kak_selection}" | xsel -i
         wid=$(xdotool getactivewindow)