Merge remote-tracking branch 'lenormf/docstring-pretty'

rc/filetype/c-family.kak

@@ -370,11 +370,12 @@ evaluate-commands %sh{
     "
 }
 
-declare-option -docstring %{control the type of include guard to be inserted in empty headers
+declare-option -docstring %{
-Can be one of the following:
+    control the type of include guard to be inserted in empty headers
- ifdef: old style ifndef/define guard
+    Can be one of the following:
- pragma: newer type of guard using "pragma once"} \
+        ifdef: old style ifndef/define guard
-    str c_include_guard_style "ifdef"
+        pragma: newer type of guard using "pragma once"
+} str c_include_guard_style "ifdef"
 
 define-command -hidden c-family-insert-include-guards %{
     evaluate-commands %sh{

rc/filetype/clojure.kak

@@ -217,8 +217,10 @@ define-command -hidden clojure-indent-on-new-line %{
     }
 }
 
-declare-option -docstring %{top-level directories which can contain clojure files
+declare-option -docstring %{
-e.g. '(src|test|dev)'} regex clojure_source_directories '(src|test|dev)'
+    top-level directories which can contain clojure files
+    e.g. '(src|test|dev)'
+} regex clojure_source_directories '(src|test|dev)'
 
 define-command -docstring %{clojure-insert-ns: Insert namespace directive at top of Clojure source file} \
     clojure-insert-ns %{

rc/tools/autowrap.kak

@@ -1,12 +1,14 @@
 declare-option -docstring "maximum amount of characters per line, after which a newline character will be inserted" \
     int autowrap_column 80
 
-declare-option -docstring %{when enabled, paragraph formatting will reformat the whole paragraph in which characters are being inserted
+declare-option -docstring %{
-This can potentially break formatting of documents containing markup (e.g. markdown)} \
+    when enabled, paragraph formatting will reformat the whole paragraph in which characters are being inserted
-    bool autowrap_format_paragraph no
+    This can potentially break formatting of documents containing markup (e.g. markdown)
-declare-option -docstring %{command to which the paragraphs to wrap will be passed
+} bool autowrap_format_paragraph no
-all occurences of '%c' are replaced with `autowrap_column`} \
+declare-option -docstring %{
-    str autowrap_fmtcmd 'fold -s -w %c'
+    command to which the paragraphs to wrap will be passed
+    all occurences of '%c' are replaced with `autowrap_column`
+} str autowrap_fmtcmd 'fold -s -w %c'
 
 define-command -hidden autowrap-cursor %{ evaluate-commands -save-regs '/"|^@m' %{
     try %{

rc/tools/clang.kak

@@ -15,9 +15,10 @@ declare-option -hidden line-specs clang_flags
 declare-option -hidden line-specs clang_errors
 
 define-command -params ..1 \
-    -docstring %{Parse the contents of the current buffer
+    -docstring %{
-The syntaxic errors detected during parsing are shown when auto-diagnostics are enabled} \
+        Parse the contents of the current buffer
-    clang-parse %{
+        The syntaxic errors detected during parsing are shown when auto-diagnostics are enabled
+    } clang-parse %{
     evaluate-commands %sh{
         dir=$(mktemp -d "${TMPDIR:-/tmp}"/kak-clang.XXXXXXXX)
         mkfifo ${dir}/fifo

rc/tools/doc.kak

@@ -147,8 +147,10 @@ define-command -params 1..2 \
             fi
         fi
     } \
-    doc -docstring %{doc <topic> [<keyword>]: open a buffer containing documentation about a given topic
+    doc -docstring %{
-An optional keyword argument can be passed to the function, which will be automatically selected in the documentation} %{
+        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
+    } %{
     evaluate-commands %sh{
         readonly page="${kak_runtime}/doc/${1}.asciidoc"
         if [ -f "${page}" ]; then

rc/tools/git.kak

@@ -22,10 +22,27 @@ declare-option -hidden line-specs git_diff_flags
 declare-option -hidden int-list git_hunk_list
 
 define-command -params 1.. \
-  -docstring %sh{printf 'git [<arguments>]: git wrapping helper
+    -docstring %{
-All the optional arguments are forwarded to the git utility
+        git [<arguments>]: git wrapping helper
-Available commands:\n  add\n  rm\n  blame\n  commit\n  checkout\n  diff\n  hide-blame\n  hide-diff\n  init\n  log\n  next-hunk\n  previous-hunk\n  show\n  show-diff\n  status\n  update-diff'} \
+        All the optional arguments are forwarded to the git utility
-  -shell-script-candidates %{
+        Available commands:
+            add
+            rm
+            blame
+            commit
+            checkout
+            diff
+            hide-blame
+            hide-diff
+            init
+            log
+            next-hunk
+            previous-hunk
+            show
+            show-diff
+            status
+            update-diff
+    } -shell-script-candidates %{
     if [ $kak_token_to_complete -eq 0 ]; then
         printf "add\nrm\nblame\ncommit\ncheckout\ndiff\nhide-blame\nhide-diff\nlog\nnext-hunk\nprev-hunk\nshow\nshow-diff\ninit\nstatus\nupdate-diff\n"
     else

rc/tools/lint.kak

@@ -1,7 +1,8 @@
-declare-option -docstring %{shell command to which the path of a copy of the current buffer will be passed
+declare-option -docstring %{
-The output returned by this command is expected to comply with the following format:
+    shell command to which the path of a copy of the current buffer will be passed
- {filename}:{line}:{column}: {kind}: {message}} \
+    The output returned by this command is expected to comply with the following format:
-    str lintcmd
+        {filename}:{line}:{column}: {kind}: {message}
+} str lintcmd
 
 declare-option -hidden line-specs lint_flags
 declare-option -hidden range-specs lint_errors

rc/tools/make.kak

@@ -8,9 +8,10 @@ declare-option -docstring "name of the client in which utilities display informa
 declare-option -hidden int make_current_error_line
 
 define-command -params .. \
-    -docstring %{make [<arguments>]: make utility wrapper
+    -docstring %{
-All the optional arguments are forwarded to the make utility} \
+        make [<arguments>]: make utility wrapper
-    make %{ evaluate-commands %sh{
+        All the optional arguments are forwarded to the make utility
+     } make %{ evaluate-commands %sh{
      output=$(mktemp -d "${TMPDIR:-/tmp}"/kak-make.XXXXXXXX)/fifo
      mkfifo ${output}
      ( eval ${kak_opt_makecmd} "$@" > ${output} 2>&1 & ) > /dev/null 2>&1 < /dev/null

rc/tools/man.kak

@@ -54,13 +54,14 @@ define-command -hidden -params 2..3 man-impl %{ evaluate-commands %sh{
 } }
 
 define-command -params ..1 \
-  -shell-script-candidates %{
+    -shell-script-candidates %{
-      find /usr/share/man/ -name '*.[1-8]*' | sed 's,^.*/\(.*\)\.\([1-8][a-zA-Z]*\).*$,\1(\2),'
+        find /usr/share/man/ -name '*.[1-8]*' | sed 's,^.*/\(.*\)\.\([1-8][a-zA-Z]*\).*$,\1(\2),'
-  } \
+    } \
-  -docstring %{man [<page>]: manpage viewer wrapper
+    -docstring %{
-If no argument is passed to the command, the selection will be used as page
+        man [<page>]: manpage viewer wrapper
-The page can be a word, or a word directly followed by a section number between parenthesis, e.g. kak(1)} \
+        If no argument is passed to the command, the selection will be used as page
-    man %{ evaluate-commands %sh{
+        The page can be a word, or a word directly followed by a section number between parenthesis, e.g. kak(1)
+    } man %{ evaluate-commands %sh{
     subject=${1-$kak_selection}
 
     ## The completion suggestions display the page number, strip them if present

rc/windowing/repl/tmux.kak

@@ -36,8 +36,10 @@ define-command tmux-repl-window -params 0..1 -command-completion -docstring "Cre
     tmux-repl-impl 'new-window' %arg{@}
 }
 
-define-command -hidden tmux-send-text -params 0..1 -docstring "tmux-send-text [text]: Send text(append new line) to the REPL pane.
+define-command -hidden tmux-send-text -params 0..1 -docstring %{
-  If no text is passed, then the selection is used" %{
+        tmux-send-text [text]: Send text(append new line) to the REPL pane.
+        If no text is passed, then the selection is used
+    } %{
     nop %sh{
         if [ $# -eq 0 ]; then
             tmux set-buffer -b kak_selection "${kak_selection}"

rc/windowing/repl/x11.kak

@@ -5,8 +5,10 @@ hook global ModuleLoaded x11 %{
 provide-module x11-repl %{
 
 # termcmd should already be set in x11.kak
-define-command -docstring %{x11-repl [<arguments>]: create a new window for repl interaction
+define-command -docstring %{
-All optional parameters are forwarded to the new window} \
+    x11-repl [<arguments>]: create a new window for repl interaction
+    All optional parameters are forwarded to the new window
+} \
     -params .. \
     -shell-completion \
     x11-repl %{ evaluate-commands %sh{