Merge remote-tracking branch 'lenormf/doc-public-options'

16 files changed, 65 insertions, 38 deletions

diff --git a/rc/base/autowrap.kak b/rc/base/autowrap.kak
index ac7fa9c2..77f507c8 100644
--- a/rc/base/autowrap.kak
+++ b/rc/base/autowrap.kak
@@ -1,11 +1,12 @@
-# Maximum amount of characters per line
-decl int autowrap_column 80
+decl -docstring "maximum amount of characters per line, after which a newline character will be inserted" \
+    int autowrap_column 80
 
-# If 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)
-decl bool autowrap_format_paragraph no
-# Command to which the paragraphs to wrap will be passed, all occurences of '%c' are replaced with `autowrap_column`
-decl str autowrap_fmtcmd 'fold -s -w %c'
+decl -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
+decl -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'
 
 def -hidden autowrap-cursor %{ eval -save-regs '/"|^@m' %{
     try %{
diff --git a/rc/base/ctags.kak b/rc/base/ctags.kak
index b4b4d7ea..101782f6 100644
--- a/rc/base/ctags.kak
+++ b/rc/base/ctags.kak
@@ -3,7 +3,8 @@
 # This script requires the readtags command available in ctags source but
 # not installed by default
 
-decl str-list ctagsfiles 'tags'
+decl -docstring "colon separated list of paths to tag files to parse when looking up a symbol" \
+    str-list ctagsfiles 'tags'
 
 def -params ..1 \
     -shell-candidates '
@@ -72,8 +73,9 @@ def ctags-enable-autoinfo -docstring "Automatically display ctags information ab
 
 def ctags-disable-autoinfo -docstring "Disable automatic ctags information displaying" %{ remove-hooks window ctags-autoinfo }
 
-decl str ctagsopts "-R"
-decl str ctagspaths "."
+decl -docstring "options to pass to the `ctags` shell command" \
+    str ctagsopts "-R"
+decl -docstring "path to the directory in which the tags file will be generated" str ctagspaths "."
 
 def ctags-generate -docstring 'Generate tag file asynchronously' %{
     echo -color Information "launching tag generation in the background"
diff --git a/rc/base/lint.kak b/rc/base/lint.kak
index acaf993c..3e6022b6 100644
--- a/rc/base/lint.kak
+++ b/rc/base/lint.kak
@@ -1,6 +1,7 @@
-# your linter should output in this format:
-# {filename}:{line}:{column}: {kind}: {message}
-decl str lintcmd
+decl -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
 
 decl -hidden line-flags lint_flags
 decl -hidden str        lint_errors
diff --git a/rc/base/x11.kak b/rc/base/x11.kak
index 61a065fe..4abe4c4a 100644
--- a/rc/base/x11.kak
+++ b/rc/base/x11.kak
@@ -1,6 +1,8 @@
 # termcmd should be set such as the next argument is the whole
 # command line to execute
-decl str termcmd %sh{
+decl -docstring %{shell command run to spawn a new terminal
+A shell command is appended to the one set in this option at runtime} \
+    str termcmd %sh{
     for termcmd in 'termite        -e      ' \
                    'urxvt          -e sh -c' \
                    'rxvt           -e sh -c' \
diff --git a/rc/core/c-family.kak b/rc/core/c-family.kak
index 81bfac3f..81a5b98c 100644
--- a/rc/core/c-family.kak
+++ b/rc/core/c-family.kak
@@ -270,7 +270,12 @@ hook -group cpp-highlight global WinSetOption filetype=(?!cpp$).* %[ remove-high
 hook -group objc-highlight global WinSetOption filetype=objc %[ add-highlighter ref objc ]
 hook -group objc-highlight global WinSetOption filetype=(?!objc$).* %[ remove-highlighter objc ]
 
-decl str c_include_guard_style "ifdef"
+decl -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"
+
 def -hidden c-family-insert-include-guards %{
     %sh{
         case "${kak_opt_c_include_guard_style}" in
@@ -287,7 +292,8 @@ def -hidden c-family-insert-include-guards %{
 
 hook global BufNewFile .*\.(h|hh|hpp|hxx|H) c-family-insert-include-guards
 
-decl str-list alt_dirs ".:.."
+decl -docstring "colon separated list of path in which header files will be looked for" \
+    str-list alt_dirs ".:.."
 
 def c-family-alternative-file -docstring "Jump to the alternate file (header/implementation)" %{ %sh{
     alt_dirs=$(printf %s\\n "${kak_opt_alt_dirs}" | tr ':' '\n')
diff --git a/rc/core/comment.kak b/rc/core/comment.kak
index 8aca996f..eebb6ab3 100644
--- a/rc/core/comment.kak
+++ b/rc/core/comment.kak
@@ -1,8 +1,10 @@
 ## Line comments
-decl str comment_line '#'
+decl -docstring "characters inserted at the beginning of a commented line" \
+    str comment_line '#'
 
 ## Block comments
-decl str-list comment_block
+decl -docstring "colon separated tuple containing the characters inserted before/after a commented line" \
+    str-list comment_block
 
 ## Default comments for all languages
 hook global BufSetOption filetype=asciidoc %{
diff --git a/rc/core/doc.kak b/rc/core/doc.kak
index d2d601e0..5456f43c 100644
--- a/rc/core/doc.kak
+++ b/rc/core/doc.kak
@@ -1,4 +1,5 @@
-decl str docsclient
+decl -docstring "name of the client in which documentation is to be displayed" \
+    str docsclient
 
 def -hidden -params 1..2 doc-open %{
     %sh{
diff --git a/rc/core/formatter.kak b/rc/core/formatter.kak
index 7238f935..46bb0661 100644
--- a/rc/core/formatter.kak
+++ b/rc/core/formatter.kak
@@ -1,4 +1,6 @@
-decl str formatcmd ""
+decl -docstring "shell command to which the contents of the current buffer is piped" \
+    str formatcmd
+
 def format -docstring "Format the contents of the current buffer" %{
     %sh{
         if [ ! -z "${kak_opt_formatcmd}" ]; then
diff --git a/rc/core/grep.kak b/rc/core/grep.kak
index e09c39a5..5cd5a1c1 100644
--- a/rc/core/grep.kak
+++ b/rc/core/grep.kak
@@ -1,5 +1,7 @@
-decl str grepcmd 'grep -RHn'
-decl str toolsclient
+decl -docstring "shell command run to search for subtext in a file/directory" \
+    str grepcmd 'grep -RHn'
+decl -docstring "name of the client in which utilities display information" \
+    str toolsclient
 decl -hidden int _grep_current_line 0
 
 def -params .. -file-completion \
@@ -41,7 +43,8 @@ hook global WinSetOption filetype=(?!grep).* %{
     remove-hooks buffer grep-hooks
 }
 
-decl str jumpclient
+decl -docstring "name of the client in which all source code jumps will be executed" \
+    str jumpclient
 
 def -hidden grep-jump %{
     eval -collapse-jumps %{
diff --git a/rc/core/make.kak b/rc/core/make.kak
index 0049a94e..72bf61e4 100644
--- a/rc/core/make.kak
+++ b/rc/core/make.kak
@@ -1,7 +1,10 @@
-decl str makecmd make
-decl str make_error_pattern " (?:fatal )?error:"
+decl -docstring "shell command run to build the project" \
+    str makecmd make
+decl -docstring "pattern that describes lines containing information about errors in the output of the `makecmd` command" \
+    str make_error_pattern " (?:fatal )?error:"
 
-decl str toolsclient
+decl -docstring "name of the client in which utilities display information" \
+    str toolsclient
 decl -hidden int make_current_error_line
 
 def -params .. \
@@ -40,7 +43,8 @@ hook global WinSetOption filetype=(?!make).* %{
     remove-hooks buffer make-hooks
 }
 
-decl str jumpclient
+decl -docstring "name of the client in which all source code jumps will be executed" \
+    str jumpclient
 
 def -hidden make-jump %{
     eval -collapse-jumps %{
diff --git a/rc/core/man.kak b/rc/core/man.kak
index 21a80348..5915f9b6 100644
--- a/rc/core/man.kak
+++ b/rc/core/man.kak
@@ -1,4 +1,5 @@
-decl str docsclient
+decl -docstring "name of the client in which documentation is to be displayed" \
+    str docsclient
 
 decl -hidden str _manpage
 
diff --git a/rc/extra/autorestore.kak b/rc/extra/autorestore.kak
index 7bec90ee..ad074116 100644
--- a/rc/extra/autorestore.kak
+++ b/rc/extra/autorestore.kak
@@ -1,5 +1,5 @@
-## If set to true, backups will be removed as soon as they have been restored
-decl bool autorestore_purge_restored true
+decl -docstring "remove backups once they've been restored" \
+    bool autorestore_purge_restored true
 
 ## Insert the content of the backup file into the current buffer, if a suitable one is found
 def autorestore-restore-buffer -docstring "Restore the backup for the current file if it exists" %{
diff --git a/rc/extra/clang.kak b/rc/extra/clang.kak
index fb51ebe3..b94bf5a6 100644
--- a/rc/extra/clang.kak
+++ b/rc/extra/clang.kak
@@ -1,4 +1,5 @@
-decl str clang_options
+decl -docstring "options to pass to the `clang` shell command" \
+    str clang_options
 
 decl -hidden str clang_tmp_dir
 decl -hidden completions clang_completions
diff --git a/rc/extra/git-tools.kak b/rc/extra/git-tools.kak
index e20f9c43..63f4eae2 100644
--- a/rc/extra/git-tools.kak
+++ b/rc/extra/git-tools.kak
@@ -1,4 +1,5 @@
-decl str docsclient
+decl -docstring "name of the client in which documentation is to be displayed" \
+    str docsclient
 
 hook -group git-log-highlight global WinSetOption filetype=git-log %{
     add-highlighter group git-log-highlight
@@ -16,8 +17,8 @@ hook -group git-status-highlight global WinSetOption filetype=git-status %{
 
 hook -group git-status-highlight global WinSetOption filetype=(?!git-status).* %{ remove-highlighter git-status-highlight }
 
-decl line-flags git_blame_flags
-decl line-flags git_diff_flags
+decl -hidden line-flags git_blame_flags
+decl -hidden line-flags git_diff_flags
 
 face GitBlame default,magenta
 face GitDiffFlags default,black
diff --git a/rc/extra/jedi.kak b/rc/extra/jedi.kak
index 6212c38f..4e467958 100644
--- a/rc/extra/jedi.kak
+++ b/rc/extra/jedi.kak
@@ -1,6 +1,7 @@
 decl -hidden str jedi_tmp_dir
 decl -hidden completions jedi_completions
-decl str-list jedi_python_path ''
+decl -docstring "colon separated list of path added to `python`'s $PYTHONPATH environment variable" \
+    str-list jedi_python_path
 
 def jedi-complete -docstring "Complete the current selection" %{
     %sh{
diff --git a/rc/extra/modeline.kak b/rc/extra/modeline.kak
index 1a3b4349..68b31acc 100644
--- a/rc/extra/modeline.kak
+++ b/rc/extra/modeline.kak
@@ -7,9 +7,8 @@
 ## Only a few options are supported, in order to prevent the
 ## buffers from poking around the configuration too much
 
-# Amount of additional lines that will be checked at the beginning
-# and the end of the buffer
-decl int modelines 5
+decl -docstring "amount of lines that will be checked at the beginning and the end of the buffer" \
+    int modelines 5
 
 def -hidden modeline-parse-impl %{
     %sh{