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`)
This commit is contained in:
Frank LENORMAND 2016-10-11 10:03:41 +03:00
parent 5440d31f99
commit f6a2925950
19 changed files with 91 additions and 57 deletions

View File

@ -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
}

View File

@ -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}}

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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"

View File

@ -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')

View File

@ -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>"

View File

@ -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>"

View File

@ -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

View File

@ -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
}

View File

@ -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 }
}

View File

@ -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"

View File

@ -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'"}
}

View File

@ -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

View File

@ -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>

View File

@ -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 " \

View File

@ -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')

View File

@ -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)