From 275abb227eeee8ed13daac07a3b0be414c4ce3ef Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Mon, 3 Feb 2020 20:53:28 +0100 Subject: [PATCH] rc: Make docstrings more readable This cosmetics commit makes use of the auto-deindentation syntax, available to docstrings. --- rc/filetype/c-family.kak | 11 ++++++----- rc/filetype/clojure.kak | 6 ++++-- rc/tools/autowrap.kak | 14 ++++++++------ rc/tools/clang.kak | 7 ++++--- rc/tools/doc.kak | 6 ++++-- rc/tools/git.kak | 25 +++++++++++++++++++++---- rc/tools/lint.kak | 9 +++++---- rc/tools/make.kak | 7 ++++--- rc/tools/man.kak | 15 ++++++++------- rc/windowing/repl/tmux.kak | 6 ++++-- rc/windowing/repl/x11.kak | 6 ++++-- 11 files changed, 72 insertions(+), 40 deletions(-) diff --git a/rc/filetype/c-family.kak b/rc/filetype/c-family.kak index 2c82a90eb..ab9f82aa1 100644 --- a/rc/filetype/c-family.kak +++ b/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 -Can be one of the following: - ifdef: old style ifndef/define guard - pragma: newer type of guard using "pragma once"} \ - str c_include_guard_style "ifdef" +declare-option -docstring %{ + control the type of include guard to be inserted in empty headers + Can be one of the following: + ifdef: old style ifndef/define guard + 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{ diff --git a/rc/filetype/clojure.kak b/rc/filetype/clojure.kak index 9e8d73b8a..901cb8b3e 100644 --- a/rc/filetype/clojure.kak +++ b/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 -e.g. '(src|test|dev)'} regex clojure_source_directories '(src|test|dev)' +declare-option -docstring %{ + 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 %{ diff --git a/rc/tools/autowrap.kak b/rc/tools/autowrap.kak index 0fb121231..c900abc66 100644 --- a/rc/tools/autowrap.kak +++ b/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 -This can potentially break formatting of documents containing markup (e.g. markdown)} \ - bool autowrap_format_paragraph no -declare-option -docstring %{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' +declare-option -docstring %{ + when enabled, paragraph formatting will reformat the whole paragraph in which characters are being inserted + This can potentially break formatting of documents containing markup (e.g. markdown) +} bool autowrap_format_paragraph no +declare-option -docstring %{ + 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 %{ diff --git a/rc/tools/clang.kak b/rc/tools/clang.kak index 9022cf266..8e9781c15 100644 --- a/rc/tools/clang.kak +++ b/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 -The syntaxic errors detected during parsing are shown when auto-diagnostics are enabled} \ - clang-parse %{ + -docstring %{ + Parse the contents of the current buffer + 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 diff --git a/rc/tools/doc.kak b/rc/tools/doc.kak index 2d1c3a0d7..b95ec54d8 100644 --- a/rc/tools/doc.kak +++ b/rc/tools/doc.kak @@ -147,8 +147,10 @@ define-command -params 1..2 \ fi fi } \ - doc -docstring %{doc []: 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} %{ + doc -docstring %{ + doc []: 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 diff --git a/rc/tools/git.kak b/rc/tools/git.kak index ccf6cfa0a..b797f1c1c 100644 --- a/rc/tools/git.kak +++ b/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 []: 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 hide-diff\n init\n log\n next-hunk\n previous-hunk\n show\n show-diff\n status\n update-diff'} \ - -shell-script-candidates %{ + -docstring %{ + git []: git wrapping helper + All the optional arguments are forwarded to the git utility + 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 diff --git a/rc/tools/lint.kak b/rc/tools/lint.kak index a9545b476..a0accd089 100644 --- a/rc/tools/lint.kak +++ b/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 -The output returned by this command is expected to comply with the following format: - {filename}:{line}:{column}: {kind}: {message}} \ - str lintcmd +declare-option -docstring %{ + shell command to which the path of a copy of the current buffer will be passed + The output returned by this command is expected to comply with the following format: + {filename}:{line}:{column}: {kind}: {message} +} str lintcmd declare-option -hidden line-specs lint_flags declare-option -hidden range-specs lint_errors diff --git a/rc/tools/make.kak b/rc/tools/make.kak index 5ae1cf524..3c4fc3acb 100644 --- a/rc/tools/make.kak +++ b/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 []: make utility wrapper -All the optional arguments are forwarded to the make utility} \ - make %{ evaluate-commands %sh{ + -docstring %{ + make []: make utility wrapper + 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 diff --git a/rc/tools/man.kak b/rc/tools/man.kak index f1f515b8d..12661c2c9 100644 --- a/rc/tools/man.kak +++ b/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 %{ - find /usr/share/man/ -name '*.[1-8]*' | sed 's,^.*/\(.*\)\.\([1-8][a-zA-Z]*\).*$,\1(\2),' - } \ - -docstring %{man []: 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 %{ evaluate-commands %sh{ + -shell-script-candidates %{ + find /usr/share/man/ -name '*.[1-8]*' | sed 's,^.*/\(.*\)\.\([1-8][a-zA-Z]*\).*$,\1(\2),' + } \ + -docstring %{ + man []: 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 %{ evaluate-commands %sh{ subject=${1-$kak_selection} ## The completion suggestions display the page number, strip them if present diff --git a/rc/windowing/repl/tmux.kak b/rc/windowing/repl/tmux.kak index 227c5496b..5e7d17db6 100644 --- a/rc/windowing/repl/tmux.kak +++ b/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. - If no text is passed, then the selection is used" %{ +define-command -hidden tmux-send-text -params 0..1 -docstring %{ + 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}" diff --git a/rc/windowing/repl/x11.kak b/rc/windowing/repl/x11.kak index 306888951..0baef9655 100644 --- a/rc/windowing/repl/x11.kak +++ b/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 []: create a new window for repl interaction -All optional parameters are forwarded to the new window} \ +define-command -docstring %{ + x11-repl []: create a new window for repl interaction + All optional parameters are forwarded to the new window +} \ -params .. \ -shell-completion \ x11-repl %{ evaluate-commands %sh{