From a25cc215e8065c246e61d89b883eeeb70bfad886 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Fri, 4 Sep 2020 19:20:50 +1000
Subject: [PATCH] Reference content goes in docstrings, explanations go in
 prose docs.

Also, make sure docstrings reference the prose docs, so people who stumble over
an interesting-looking command or option can find out more about it.
---
 rc/tools/autorestore.kak | 30 ++++++++++++++++++++++++++----
 rc/tools/doc.kak         |  2 ++
 rc/tools/lint.asciidoc   |  7 ++++---
 rc/tools/lint.kak        | 12 ++++--------
 4 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/rc/tools/autorestore.kak b/rc/tools/autorestore.kak
index a59ce850..d3e60994 100644
--- a/rc/tools/autorestore.kak
+++ b/rc/tools/autorestore.kak
@@ -1,8 +1,18 @@
-declare-option -docstring "remove backups once they've been restored" \
+declare-option -docstring %{
+        Remove backups once they've been restored
+
+        See `:doc autorestore` for details.
+    } \
     bool autorestore_purge_restored true
 
 ## Insert the content of the backup file into the current buffer, if a suitable one is found
-define-command autorestore-restore-buffer -docstring "Restore the backup for the current file if it exists" %{
+define-command autorestore-restore-buffer \
+    -docstring %{
+        Restore the backup for the current file if it exists
+
+        See `:doc autorestore` for details.
+    } \
+%{
     evaluate-commands %sh{
         buffer_basename="${kak_buffile##*/}"
         buffer_dirname=$(dirname "${kak_buffile}")
@@ -48,7 +58,13 @@ define-command autorestore-restore-buffer -docstring "Restore the backup for the
 }
 
 ## Remove all the backups that have been created for the current buffer
-define-command autorestore-purge-backups -docstring "Remove all the backups of the current buffer" %{
+define-command autorestore-purge-backups \
+    -docstring %{
+        Remove all the backups of the current buffer
+
+        See `:doc autorestore` for details.
+    } \
+%{
     evaluate-commands %sh{
         [ ! -f "${kak_buffile}" ] && exit
 
@@ -64,7 +80,13 @@ define-command autorestore-purge-backups -docstring "Remove all the backups of t
 }
 
 ## If for some reason, backup files need to be ignored
-define-command autorestore-disable -docstring "Disable automatic backup recovering" %{
+define-command autorestore-disable \
+    -docstring %{
+        Disable automatic backup recovering
+
+        See `:doc autorestore` for details.
+    } \
+%{
     remove-hooks global autorestore
 }
 
diff --git a/rc/tools/doc.kak b/rc/tools/doc.kak
index d88dcda2..5a6c8e1d 100644
--- a/rc/tools/doc.kak
+++ b/rc/tools/doc.kak
@@ -163,6 +163,8 @@ define-command -params 1..2 \
     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
+
+        See `:doc doc` for details.
     } %{
     evaluate-commands %sh{
         page=$(
diff --git a/rc/tools/lint.asciidoc b/rc/tools/lint.asciidoc
index 3fe7f5ad..469b1e57 100644
--- a/rc/tools/lint.asciidoc
+++ b/rc/tools/lint.asciidoc
@@ -12,9 +12,10 @@ If the 'kind' field contains 'error', the message is treated as an error,
 otherwise it is assumed to be a warning.
 
 The `:lint-buffer` and `:lint-selections` commands will run the shell command
-specified in the `lintcmd` option, collect the result in the `*lint-output*`
-buffer, and analyze it. If `toolsclient` is set, the `*lint-output*` buffer will
-be displayed in the named client.
+specified in the `lintcmd` option, passing it the path to a temporary file
+containing the text to be linted. The results are collected in the
+`*lint-output*` buffer, and analyze it. If `toolsclient` is set, the
+`*lint-output*` buffer will be displayed in the named client.
 
 Each reported error or warning causes a marker to appear in the left-hand
 margin of the buffer that was checked. When the main cursor moves onto that
diff --git a/rc/tools/lint.kak b/rc/tools/lint.kak
index abacf8fd..c53b6b71 100644
--- a/rc/tools/lint.kak
+++ b/rc/tools/lint.kak
@@ -2,13 +2,7 @@ declare-option \
     -docstring %{
         The shell command used by lint-buffer and lint-selections.
 
-        It will be given the path to a file containing the text to be
-        linted, and must produce output in the format:
-
-            {filename}:{line}:{column}: {kind}: {message}
-
-        If the 'kind' field contains 'error', the message is treated
-        as an error, otherwise it is assumed to be a warning.
+        See `:doc lint` for details.
     } \
     str lintcmd
 
@@ -230,6 +224,8 @@ define-command \
         Switches:
             -command <cmd>      Use the given linter.
                                 If not given, the lintcmd option is used.
+
+        See `:doc lint` for details.
     } \
     lint-selections \
 %{
@@ -275,7 +271,7 @@ define-command \
     -docstring %{
         lint-buffer: Check the current buffer with a linter.
 
-        Set the lintcmd option to control which linter is used.
+        See `:doc lint` for details.
     } \
     lint-buffer \
 %{