docs: deprecate :checkhealth vimscript interface

2 files changed, 47 insertions, 98 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index eb6d9b6dc9..b1dd650e7d 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -47,6 +47,11 @@ Functions ~
 *buffer_name()*		Obsolete name for |bufname()|.
 *buffer_number()*	Obsolete name for |bufnr()|.
 *file_readable()*	Obsolete name for |filereadable()|.
+*health#report_error*	Use Lua |vim.health.report_error()| instead.
+*health#report_info*	Use Lua |vim.health.report_info()| instead.
+*health#report_ok*	Use Lua |vim.health.report_ok()| instead.
+*health#report_start*	Use Lua |vim.health.report_start()| instead.
+*health#report_warn*	Use Lua |vim.health.report_warn()| instead.
 *highlight_exists()*	Obsolete name for |hlexists()|.
 *highlightID()*		Obsolete name for |hlID()|.
 *inputdialog()*		Use |input()| instead.
diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt
index 04e04b5165..cc36e7186c 100644
--- a/runtime/doc/pi_health.txt
+++ b/runtime/doc/pi_health.txt
@@ -7,11 +7,12 @@ Author: TJ DeVries <devries.timothyj@gmail.com>
 ==============================================================================
 Introduction                            *health*
 
-health.vim is a minimal framework to help with troubleshooting user
-configuration. Nvim ships with healthchecks for configuration, performance,
-python support, ruby support, clipboard support, and more.
+health.vim is a minimal framework to help users troubleshoot configuration and
+any other environment conditions that a plugin might care about. Nvim ships
+with healthchecks for configuration, performance, python support, ruby
+support, clipboard support, and more.
 
-To run the healthchecks, use this command: >
+To run all healthchecks, use: >
 
         :checkhealth
 <
@@ -21,7 +22,7 @@ Plugin authors are encouraged to write new healthchecks. |health-dev|
 Commands                                *health-commands*
 
                                         *:checkhealth* *:CheckHealth*
-:checkhealth          Run all healthchecks.
+:checkhealth    Run all healthchecks.
                                         *E5009*
                 Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
                 find the standard "runtime files" for syntax highlighting,
@@ -35,23 +36,21 @@ Commands                                *health-commands*
                         :checkhealth nvim
 <
                 To run the healthchecks for the "foo" and "bar" plugins
-                (assuming these plugins are on 'runtimepath' or 'packpath' and
-                they have implemented the Lua or Vimscript interface
-                require("foo.health").check() and health#bar#check(),
-                respectively): >
+                (assuming they are on 'runtimepath' and they have implemented
+                the Lua `require("foo.health").check()` interface): >
                         :checkhealth foo bar
 <
-                To run healthchecks for lua submodules, use dot notation or
-                "*" to refer to all submodules. For example nvim provides
-                `vim.lsp` and `vim.treesitter`  >
+                To run healthchecks for Lua submodules, use dot notation or
+                "*" to refer to all submodules. For example Nvim provides
+                `vim.lsp` and `vim.treesitter`:  >
                         :checkhealth vim.lsp vim.treesitter
                         :checkhealth vim*
 <
 ==============================================================================
-Lua Functions                       *health-functions-lua* *health-lua* *vim.health*
+Functions                               *health-functions* *vim.health*
 
-The Lua "health" module can be used to create new healthchecks (see also
-|health-functions-vim|). To get started, simply use:
+The Lua "health" module can be used to create new healthchecks. To get started
+see |health-dev|.
 
 vim.health.report_start({name})                         *vim.health.report_start()*
         Starts a new report. Most plugins should call this only once, but if
@@ -65,36 +64,43 @@ vim.health.report_ok({msg})                             *vim.health.report_ok()*
         Reports a "success" message.
 
 vim.health.report_warn({msg} [, {advice}])              *vim.health.report_warn()*
-        Reports a warning. {advice} is an optional List of suggestions.
+        Reports a warning. {advice} is an optional list of suggestions to
+        present to the user.
 
 vim.health.report_error({msg} [, {advice}])             *vim.health.report_error()*
-        Reports an error. {advice} is an optional List of suggestions.
+        Reports an error. {advice} is an optional list of suggestions to
+        present to the user.
 
 ==============================================================================
-Create a Lua healthcheck                *health-dev-lua*
-
-Healthchecks are functions that check the user environment, configuration,
-etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/.
-
-To add a new healthcheck for your own plugin, simply define a Lua module in
-your plugin that returns a table with a "check()" function. |:checkhealth|
-will automatically find and invoke this function.
-
-If your plugin is named "foo", then its healthcheck module should be a file in
-one of these locations on 'runtimepath' or 'packpath':
+Create a healthcheck                                    *health-dev*
+
+Healthchecks are functions that check the user environment, configuration, or
+any other prerequisities that a plugin cares about. Nvim ships with
+healthchecks in:
+        - $VIMRUNTIME/autoload/health/
+        - $VIMRUNTIME/lua/vim/lsp/health.lua
+        - $VIMRUNTIME/lua/vim/treesitter/health.lua
+        - and more...
+
+To add a new healthcheck for your own plugin, simply create a "health.lua"
+module on 'runtimepath' that returns a table with a "check()" function. Then
+|:checkhealth| will automatically find and invoke the function.
+
+For example if your plugin is named "foo", define your healthcheck module at
+one of these locations (on 'runtimepath'):
         - lua/foo/health/init.lua
         - lua/foo/health.lua
 
-If your plugin provides a submodule named "bar" for which you want a separate
-healthcheck, define the healthcheck at one of these locations on 'runtimepath'
-or 'packpath':
+If your plugin also provides a submodule named "bar" for which you want
+a separate healthcheck, define the healthcheck at one of these locations:
         - lua/foo/bar/health/init.lua
         - lua/foo/bar/health.lua
 
-All submodules should return a Lua table containing the method `check()`.
+All such health modules must return a Lua table containing a `check()`
+function.
 
-Copy this sample code into `lua/foo/health/init.lua` or `lua/foo/health.lua`,
-replacing "foo" in the path with your plugin name: >
+Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path
+with your plugin name: >
 
         local M = {}
 
@@ -102,9 +108,9 @@ replacing "foo" in the path with your plugin name: >
           vim.health.report_start("my_plugin report")
           -- make sure setup function parameters are ok
           if check_setup() then
-            vim.health.report_ok("Setup function is correct")
+            vim.health.report_ok("Setup is correct")
           else
-            vim.health.report_error("Setup function is incorrect")
+            vim.health.report_error("Setup is incorrect")
           end
           -- do some more checking
           -- ...
@@ -112,67 +118,5 @@ replacing "foo" in the path with your plugin name: >
 
         return M
 
-==============================================================================
-Vimscript Functions             *health-functions-vimscript* *health-vimscript*
-
-health.vim functions are for creating new healthchecks. (See also
-|health-functions-lua|)
-
-health#report_start({name})                             *health#report_start*
-        Starts a new report. Most plugins should call this only once, but if
-        you want different sections to appear in your report, call this once
-        per section.
-
-health#report_info({msg})                               *health#report_info*
-        Reports an informational message.
-
-health#report_ok({msg})                                 *health#report_ok*
-        Reports a "success" message.
-
-health#report_warn({msg} [, {advice}])                  *health#report_warn*
-        Reports a warning. {advice} is an optional List of suggestions.
-
-health#report_error({msg} [, {advice}])                 *health#report_error*
-        Reports an error. {advice} is an optional List of suggestions.
-
-health#{plugin}#check()                                 *health.user_checker*
-        Healthcheck function for {plugin}. Called by |:checkhealth|
-        automatically. Example: >
-
-        function! health#my_plug#check() abort
-          silent call s:check_environment_vars()
-          silent call s:check_python_configuration()
-        endfunction
-<
-==============================================================================
-Create a healthcheck                    *health-dev-vim*
-
-Healthchecks are functions that check the user environment, configuration,
-etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/.
-
-To add a new healthcheck for your own plugin, simply define a
-health#{plugin}#check() function in autoload/health/{plugin}.vim.
-|:checkhealth| automatically finds and invokes such functions.
-
-If your plugin is named "foo", then its healthcheck function must be >
-        health#foo#check()
-
-defined in this file on 'runtimepath' or 'packpath':
-        - autoload/health/foo.vim
-
-Copy this sample code into autoload/health/foo.vim and replace "foo" with your
-plugin name: >
-        function! health#foo#check() abort
-          call health#report_start('sanity checks')
-          " perform arbitrary checks
-          " ...
-        
-          if looks_good
-            call health#report_ok('found required dependencies')
-          else
-            call health#report_error('cannot find foo', 
-              \ ['npm install --save foo'])
-          endif
-        endfunction
 
 vim:et:tw=78:ts=8:ft=help:fdm=marker