Merge remote-tracking branch 'lenormf/doctrings_update'

rc/autowrap.kak

@@ -2,7 +2,7 @@
 decl int autowrap_column 80
 
 ## Automatically wrap the selection
-def autowrap-selection %{
+def autowrap-selection -docstring "Wrap the selection" %{
     try %{
         ## <a-:><a-;>: ensure that the cursor is located after the anchor, then reverse the
         ##             selection (make sure the cursor is at the beginning of the selection)
@@ -20,7 +20,7 @@ def autowrap-selection %{
 }
 
 ## Add a hook that will wrap the entire line every time a key is pressed
-def autowrap-enable %{
+def autowrap-enable -docstring "Wrap the lines in which characters are inserted" %{
     hook -group autowrap window InsertChar [^\n] %{
         try %{
             exec -draft "<a-x>:autowrap-selection<ret>"
@@ -29,6 +29,6 @@ def autowrap-enable %{
 }
 
 ## Disable the automatic line wrapping, autowrap-selection remains available though
-def autowrap-disable %{
+def autowrap-disable -docstring "Disable automatic line wrapping" %{
     rmhooks window autowrap
 }

rc/clang.kak

@@ -5,7 +5,7 @@ decl -hidden str-list clang_completions
 decl -hidden line-flag-list clang_flags
 decl -hidden str clang_errors
 
-def -shell-params clang-parse %{
+def -shell-params clang-parse -docstring "Parse the contents of the current buffer with clang" %{
     %sh{
         dir=$(mktemp -d -t kak-clang.XXXXXXXX)
         mkfifo ${dir}/fifo
@@ -85,9 +85,9 @@ def -shell-params clang-parse %{
     }
 }
 
-def clang-complete %{ clang-parse -complete }
+def clang-complete -docstring "Complete the current selection with clang" %{ clang-parse -complete }
 
-def clang-enable-autocomplete %{
+def clang-enable-autocomplete -docstring "Enable completion with clang" %{
     set window completers "option=clang_completions:%opt{completers}"
     hook window -group clang-autocomplete InsertIdle .* %{ try %{
         exec -draft <a-h><a-k>(\.|->|::).\'<ret>
@@ -97,7 +97,7 @@ def clang-enable-autocomplete %{
     alias window complete clang-complete
 }
 
-def clang-disable-autocomplete %{
+def clang-disable-autocomplete -docstring "Disable automatic clang completion" %{
     set window completers %sh{ echo "'${kak_opt_completers}'" | sed -e 's/option=clang_completions://g' }
     rmhooks window clang-autocomplete
     unalias window complete clang-complete
@@ -111,17 +111,17 @@ def -hidden clang-show-error-info %{ %sh{
     done
 } }
 
-def clang-enable-diagnostics %{
+def clang-enable-diagnostics -docstring "Activate automatic diagnostics of the code by clang" %{
     addhl flag_lines default clang_flags
     hook window -group clang-diagnostics NormalIdle .* %{ clang-show-error-info }
 }
 
-def clang-disable-diagnostics %{
+def clang-disable-diagnostics -docstring "Disable automatic diagnostics of the code" %{
     rmhl hlflags_clang_flags
     rmhooks window clang-diagnostics
 }
 
-def clang-diagnostics-next %{ %sh{
+def clang-diagnostics-next -docstring "Jump to the next line that contains an error" %{ %sh{
     echo "${kak_opt_clang_errors}" | (
         line=-1
         first_line=-1

rc/ctags.kak

@@ -7,7 +7,7 @@ decl str-list ctagsfiles 'tags'
 
 def -shell-params \
     -shell-completion 'readtags -p "$1" | cut -f 1 | sort | uniq' \
-    -docstring 'jump to tag definition' \
+    -docstring 'Jump to tag definition' \
     tag \
     %{ %sh{
         export tagname=${1:-${kak_selection}}
@@ -25,7 +25,7 @@ def -shell-params \
             END { print length(out) == 0 ? "echo -color Error no such tag " ENVIRON["tagname"] : "menu -auto-single " out }'
     }}
 
-def tag-complete %{ eval -draft %{
+def tag-complete -docstring "Insert completion candidates for the current selection into the buffer's local variables" %{ eval -draft %{
     exec <space>hb<a-k>^\w+$<ret>
     %sh{ (
         compl=$(readtags -p "$kak_selection" | cut -f 1 | sort | uniq | sed -e 's/:/\\:/g' | sed -e 's/\n/:/g' )
@@ -34,28 +34,30 @@ def tag-complete %{ eval -draft %{
     ) > /dev/null 2>&1 < /dev/null & }
 }}
 
-def funcinfo %{
+def ctags-funcinfo -docstring "Display ctags information about a selected function" %{
     eval -draft %{
-        exec '[(;B<a-k>[a-zA-Z_]+\(<ret><a-;>'
-        %sh{
-            sigs=$(readtags -e ${kak_selection%(} | grep kind:f | sed -re 's/^(\S+).*((class|struct|namespace):(\S+))?.*signature:(.*)$/\5 [\4::\1]/')
-            if [ -n "$sigs" ]; then
-                echo "eval -client ${kak_client} %{info -anchor $kak_cursor_line.$kak_cursor_column -placement above '$sigs'}"
-            fi
+        try %{
+            exec '[(;B<a-k>[a-zA-Z_]+\(<ret><a-;>'
+            %sh{
+                sigs=$(readtags -e ${kak_selection%(} | grep kind:f | sed -re 's/^(\S+).*((class|struct|namespace):(\S+))?.*signature:(.*)$/\5 [\4::\1]/')
+                if [ -n "$sigs" ]; then
+                    echo "eval -client ${kak_client} %{info -anchor $kak_cursor_line.$kak_cursor_column -placement above '$sigs'}"
+                fi
+            }
         }
     }
 }
 
-def ctags-enable-autoinfo %{
-     hook window -group ctags-autoinfo NormalKey .* funcinfo
-     hook window -group ctags-autoinfo InsertKey .* funcinfo
+def ctags-enable-autoinfo -docstring "Automatically display ctags information about function" %{
+     hook window -group ctags-autoinfo NormalKey .* ctags-funcinfo
+     hook window -group ctags-autoinfo InsertKey .* ctags-funcinfo
 }
 
-def ctags-disable-autoinfo %{ rmhooks window ctags-autoinfo }
+def ctags-disable-autoinfo -docstring "Disable automatic ctags information displaying" %{ rmhooks window ctags-autoinfo }
 
 decl str ctagsopts "-R ."
 
-def gentags -docstring 'generate tag file asynchronously' %{
+def gentags -docstring 'Generate tag file asynchronously' %{
     echo -color Information "launching tag generation in the background"
     %sh{ (
         if ctags -f .tags.kaktmp ${kak_opt_ctagsopts}; then

rc/git-tools.kak

@@ -23,7 +23,7 @@ decl line-flag-list git_blame_flags
 decl line-flag-list git_diff_flags
 
 def -shell-params \
-  -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 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}"} \
   -shell-completion %{
     shift $(expr ${kak_token_to_complete})
     prefix=${1:0:${kak_pos_in_token}}

rc/golang.kak

@@ -59,13 +59,13 @@ def -hidden _golang-indent-on-closing-curly-brace %[
     try %[ exec -itersel -draft <a-h><a-k>^\h+\}$<ret>hms\`|.\'<ret>1<a-&> ]
 ]
 
-def golang-enable-gofmt %{
+def golang-enable-gofmt -docstring "Format the code using the gofmt utility upon saving" %{
     hook buffer -group golang-formatter BufWritePre .* %{
         exec -draft %{%|"gofmt"<ret>}
     }
 }
 
-def golang-disable-gofmt %{
+def golang-disable-gofmt -docstring "Disable automatic code formatting" %{
 	rmhooks buffer golang-formatter
 }
 

rc/grep.kak

@@ -3,7 +3,7 @@ decl str toolsclient
 decl -hidden int _grep_current_line 0
 
 def -shell-params -file-completion \
-    grep %{ %sh{
+    grep -docstring "Grep utility wrapper" %{ %sh{
      output=$(mktemp -d -t kak-grep.XXXXXXXX)/fifo
      mkfifo ${output}
      if [ $# -gt 0 ]; then
@@ -34,14 +34,16 @@ hook global WinSetOption filetype=(?!grep).* %{ rmhl grep; rmhooks buffer grep-h
 
 decl str jumpclient
 
-def jump %{
-    exec 'xs^((?:\w:)?[^:]+):(\d+):(\d+)?<ret>'
-    set buffer _grep_current_line %val{cursor_line}
-    eval -try-client %opt{jumpclient} edit -existing %reg{1} %reg{2} %reg{3}
-    try %{ focus %opt{jumpclient} }
+def grep-jump %{
+    try %{
+        exec 'xs^((?:\w:)?[^:]+):(\d+):(\d+)?<ret>'
+        set buffer _grep_current_line %val{cursor_line}
+        eval -try-client %opt{jumpclient} edit -existing %reg{1} %reg{2} %reg{3}
+        try %{ focus %opt{jumpclient} }
+    }
 }
 
-def next -docstring 'Jump to next grep match' %{
+def grep-next -docstring 'Jump to next grep match' %{
     eval -try-client %opt{jumpclient} %{
         buffer '*grep*'
         exec "%opt{_grep_current_line}g<a-l>/^[^:]+:\d+:<ret>"
@@ -49,7 +51,7 @@ def next -docstring 'Jump to next grep match' %{
     }
 }
 
-def prev -docstring 'Jump to previous grep match' %{
+def grep-prev -docstring 'Jump to previous grep match' %{
     eval -try-client %opt{jumpclient} %{
         buffer '*grep*'
         exec "%opt{_grep_current_line}g<a-/>^[^:]+:\d+:<ret>"

rc/jedi.kak

@@ -1,7 +1,7 @@
 decl -hidden str jedi_tmp_dir
 decl -hidden str-list jedi_completions
 
-def jedi-complete %{
+def jedi-complete -docstring "Complete the current selection with jedi" %{
     %sh{
         dir=$(mktemp -d -t kak-jedi.XXXXXXXX)
         mkfifo ${dir}/fifo
@@ -27,7 +27,7 @@ def jedi-complete %{
     }
 }
 
-def jedi-enable-autocomplete %{
+def jedi-enable-autocomplete -docstring "Add jedi completion candidates to the completer" %{
     set window completers "option=jedi_completions:%opt{completers}"
     hook window -group jedi-autocomplete InsertIdle .* %{ try %{
         exec -draft <a-h><a-k>\..\'<ret>
@@ -37,7 +37,7 @@ def jedi-enable-autocomplete %{
     alias window complete jedi-complete
 }
 
-def jedi-disable-autocomplete %{
+def jedi-disable-autocomplete -docstring "Disable jedi completion" %{
     set window completers %sh{ echo "'${kak_opt_completers}'" | sed -e 's/option=jedi_completions://g' }
     rmhooks window jedi-autocomplete
     unalias window complete jedi-complete

rc/make.kak

@@ -2,7 +2,7 @@ decl str makecmd make
 decl str toolsclient
 decl -hidden int _make_current_error_line
 
-def -shell-params make %{ %sh{
+def -shell-params make -docstring "Make utility wrapper" %{ %sh{
      output=$(mktemp -d -t kak-make.XXXXXXXX)/fifo
      mkfifo ${output}
      ( eval ${kak_opt_makecmd} "$@" > ${output} 2>&1 ) > /dev/null 2>&1 < /dev/null &

rc/man.kak

@@ -44,7 +44,7 @@ def -shell-params \
         esac
     done
   } \
-  man %{ %sh{
+  man -docstring "Manpages viewer wrapper" %{ %sh{
     [ -z "$@" ] && set -- "$kak_selection"
     echo "eval -try-client %opt{docsclient} _man $@"
 } }