docs(runtime/health): update with new lua support

- describe how the lua support works
- explain new behavior of :checkhealth *
- fixed formatting to use tab instead of spaces

1 files changed, 122 insertions, 53 deletions

diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt
index bb688770fc..69655ba902 100644
--- a/runtime/doc/pi_health.txt
+++ b/runtime/doc/pi_health.txt
@@ -13,7 +13,7 @@ python support, ruby support, clipboard support, and more.
 
 To run the healthchecks, use this command: >
 
-        :checkhealth
+	:checkhealth
 <
 Plugin authors are encouraged to write new healthchecks. |health-dev|
 
@@ -23,32 +23,107 @@ Commands				*health-commands*
 					*:checkhealth* *:CheckHealth*
 :checkhealth          Run all healthchecks.
 					*E5009*
-                      Nvim depends on |$VIMRUNTIME| and 'runtimepath' to find
-                      the standard "runtime files" for syntax highlighting,
-                      filetype-specific behavior, and standard plugins
-                      (including :checkhealth).  If the runtime files cannot
-                      be found then those features will not work.
+		Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
+		find the standard "runtime files" for syntax highlighting,
+		filetype-specific behavior, and standard plugins (including
+		:checkhealth).  If the runtime files cannot be found then
+		those features will not work.
 
 :checkhealth {plugins}
-                      Run healthcheck(s) for one or more plugins. E.g. to run
-                      only the standard Nvim healthcheck: >
-                        :checkhealth nvim
-<                      To run the healthchecks for the "foo" and "bar" plugins
-                      (assuming these plugins are on your 'runtimepath' and
-                      they have implemented health#foo#check() and
-                      health#bar#check(), respectively): >
-                        :checkhealth foo bar
+		Run healthcheck(s) for one or more plugins. E.g. to run only
+		the standard Nvim healthcheck: >
+			: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): >
+			: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`  >
+			:checkhealth vim.lsp vim.treesitter
+			:checkhealth vim*
+<
+==============================================================================
+Lua Functions				*health-functions-lua* *health-lua*
+
+The Lua "health" module can be used to create new healthchecks (see also
+|health-functions-vim|). To get started, simply use:  >
+	local health = require('health')
+<
+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.
+
+==============================================================================
+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':
+	- `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':
+	- `lua/foo/bar/health/init.lua`
+	- `lua/foo/bar/health.lua`
+
+All submodules should return a Lua table containing the method `check()`.
+
+Copy this sample code into `lua/foo/health/init.lua` or `lua/foo/health.lua`,
+replacing "foo" in the path with your plugin name: >
+
+	local M = {}
+	local health = require("health")
+
+	M.check = function()
+	  health.report_start("my_plugin report")
+	  -- make sure setup function parameters are ok
+	  if check_setup() then
+	    health.report_ok("Setup function is correct")
+	  else
+	    health.report_error("Setup function is incorrect")
+	  end
+	  -- do some more checking
+	  -- ...
+	end
+
+	return M
+
 ==============================================================================
-Functions				*health-functions*
+Vimscript Functions		*health-functions-vimscript* *health-vimscript*
 
-health.vim functions are for creating new healthchecks. They mostly just do
-some layout and formatting, to give users a consistent presentation.
+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.
+	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.
@@ -56,27 +131,23 @@ health#report_info({msg})				*health#report_info*
 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_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#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: >
+	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
+	function! health#my_plug#check() abort
+	  silent call s:check_environment_vars()
+	  silent call s:check_python_configuration()
+	endfunction
 <
-	All output will be captured from the healthcheck. Use the
-        health#report_* functions so that your healthcheck has a format
-        consistent with the standard healthchecks.
-
 ==============================================================================
-Create a healthcheck			*health-dev*
+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/.
@@ -86,26 +157,24 @@ 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()
+	health#foo#check()
 
-defined in this file on 'runtimepath': >
-        autoload/health/foo.vim
+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:tw=78:ts=8:ft=help:fdm=marker
+	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:noet tw=78:ts=8:ft=help:fdm=marker