diff --git a/rc/base/autowrap.kak b/rc/base/autowrap.kak
index 18eaf6b9..273e7077 100644
--- a/rc/base/autowrap.kak
+++ b/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
 }
 
diff --git a/rc/base/ctags.kak b/rc/base/ctags.kak
index d076cef0..18e125fc 100644
--- a/rc/base/ctags.kak
+++ b/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}}
diff --git a/rc/base/spell.kak b/rc/base/spell.kak
index 23708c1d..79127ec8 100644
--- a/rc/base/spell.kak
+++ b/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
diff --git a/rc/base/tmux.kak b/rc/base/tmux.kak
index 70c5115e..ba555533 100644
--- a/rc/base/tmux.kak
+++ b/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
diff --git a/rc/base/x11.kak b/rc/base/x11.kak
index bf932298..0583d183 100644
--- a/rc/base/x11.kak
+++ b/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
diff --git a/rc/core/doc.kak b/rc/core/doc.kak
index 88c0013f..16d5393c 100644
--- a/rc/core/doc.kak
+++ b/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"
 
diff --git a/rc/core/formatter.kak b/rc/core/formatter.kak
index 2af8eef2..7238f935 100644
--- a/rc/core/formatter.kak
+++ b/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')
diff --git a/rc/core/grep.kak b/rc/core/grep.kak
index 1752d19a..78385f2b 100644
--- a/rc/core/grep.kak
+++ b/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>"
diff --git a/rc/core/make.kak b/rc/core/make.kak
index 52aee039..f53cb272 100644
--- a/rc/core/make.kak
+++ b/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>"
diff --git a/rc/core/man.kak b/rc/core/man.kak
index edede3e1..a73d0f68 100644
--- a/rc/core/man.kak
+++ b/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
diff --git a/rc/extra/clang.kak b/rc/extra/clang.kak
index 0466a756..daeb8c83 100644
--- a/rc/extra/clang.kak
+++ b/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
 }
diff --git a/rc/extra/flake8.kak b/rc/extra/flake8.kak
index e8f77996..ed1213e8 100644
--- a/rc/extra/flake8.kak
+++ b/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 }
 }
diff --git a/rc/extra/git-tools.kak b/rc/extra/git-tools.kak
index 5478d298..455ae45a 100644
--- a/rc/extra/git-tools.kak
+++ b/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"
diff --git a/rc/extra/iterm.kak b/rc/extra/iterm.kak
index b3e36779..436889ab 100644
--- a/rc/extra/iterm.kak
+++ b/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'"}
 }
diff --git a/rc/extra/jedi.kak b/rc/extra/jedi.kak
index 61ff5c85..bb79f423 100644
--- a/rc/extra/jedi.kak
+++ b/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
diff --git a/rc/extra/modeline.kak b/rc/extra/modeline.kak
index f4a69d18..962b3f41 100644
--- a/rc/extra/modeline.kak
+++ b/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>
diff --git a/rc/extra/ranger.kak b/rc/extra/ranger.kak
index 134249e3..e05bb99f 100644
--- a/rc/extra/ranger.kak
+++ b/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 " \
diff --git a/rc/extra/tmux-repl.kak b/rc/extra/tmux-repl.kak
index 55919d0e..fbc63a19 100644
--- a/rc/extra/tmux-repl.kak
+++ b/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')
diff --git a/rc/extra/x11-repl.kak b/rc/extra/x11-repl.kak
index 1cf2db3f..cad7a37d 100644
--- a/rc/extra/x11-repl.kak
+++ b/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)