From f6a2925950baa85d6b3835e6f418bbecd11a9295 Mon Sep 17 00:00:00 2001
From: Frank LENORMAND <lenormf@gmail.com>
Date: Tue, 11 Oct 2016 10:03:41 +0300
Subject: [PATCH] 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   |  2 +-
 rc/base/ctags.kak      |  5 +++--
 rc/base/spell.kak      |  8 +++++++-
 rc/base/tmux.kak       | 15 +++++++--------
 rc/base/x11.kak        | 12 ++++++------
 rc/core/doc.kak        |  3 ++-
 rc/core/formatter.kak  |  2 +-
 rc/core/grep.kak       | 10 ++++++----
 rc/core/make.kak       | 11 +++++++----
 rc/core/man.kak        |  7 +++++--
 rc/extra/clang.kak     | 15 ++++++++++-----
 rc/extra/flake8.kak    |  4 ++--
 rc/extra/git-tools.kak |  4 +++-
 rc/extra/iterm.kak     | 19 ++++++++++++++-----
 rc/extra/jedi.kak      |  2 +-
 rc/extra/modeline.kak  |  2 +-
 rc/extra/ranger.kak    | 10 ++++++----
 rc/extra/tmux-repl.kak |  8 ++++----
 rc/extra/x11-repl.kak  |  9 +++++----
 19 files changed, 91 insertions(+), 57 deletions(-)

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)