fix(build): vimdoc tags are not validated #32801

Problem:
"make lintdoc" is not validating vimdoc (:help) tags.

Solution:
- Call `lang_tree:parse()` to init the parser.
- Load netrw 🤢 explicitly, since it was moved to `pack/dist/opt/`.
- Fix invalid help tags.

14 files changed, 33 insertions, 31 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index f841519232..3a579ab194 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -1420,8 +1420,8 @@ vimrc file again).
 						*FileExplorer*
 There is one group that is recognized by Vim: FileExplorer.  If this group
 exists Vim assumes that editing a directory is possible and will trigger a
-plugin that lists the files in that directory.  This is used by the |netrw|
-plugin.  This allows you to do: >
+plugin that lists the files in that directory.  This is used by directory
+browser plugins.  This allows you to do: >
 	browse edit
 
 ==============================================================================
@@ -1695,7 +1695,7 @@ and "++ff=" argument that are effective.  These should be used for the command
 that reads/writes the file.  The |v:cmdbang| variable is one when "!" was
 used, zero otherwise.
 
-See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples.
+See the $VIMRUNTIME/pack/dist/opt/netrw/plugin/netrwPlugin.vim for examples.
 
 ==============================================================================
 11. Disabling autocommands				*autocmd-disable*
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index d3170f114f..8d60d2c868 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -376,10 +376,10 @@ Where possible, these patterns apply to _both_ Lua and the API:
   - See |vim.lsp.inlay_hint.enable()| and |vim.lsp.inlay_hint.is_enabled()|
     for a reference implementation of these "best practices".
   - NOTE: open questions: https://github.com/neovim/neovim/issues/28603
-- Transformation functions should also have a filter functionality when
-  appropriate. That is, when the function returns a nil value it "filters" its
-  input, otherwise the transformed value is used.
-  - Example: |vim.diagnostic.config.format()|
+- Transformation functions should also have "filter" functionality (when
+  appropriate): when the function returns a nil value it excludes (filters
+  out) its input, else the transformed value is used.
+  - Example: See the format() field of |vim.diagnostic.Opts.Float|.
 
 API DESIGN GUIDELINES                                   *dev-api*
 
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index 4224709a39..c275bf863d 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -1496,9 +1496,8 @@ Or, when starting gvim from a shell: >
 Note that if a FileChangedShell autocommand is defined you will not get a
 warning message or prompt.  The autocommand is expected to handle this.
 
-There is no warning for a directory (e.g., with |netrw-browse|).  But you do
-get warned if you started editing a new file and it was created as a directory
-later.
+There is no warning for a directory.  But you do get warned if you started
+editing a new file and it was created as a directory later.
 
 When Vim notices the timestamp of a file has changed, and the file is being
 edited in a buffer but has not changed, Vim checks if the contents of the file
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index 914dc64c0a..991b3d02c8 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -180,11 +180,11 @@ Standard plugins ~
 						*standard-plugin-list*
 |pi_gzip.txt|		Reading and writing compressed files
 |pi_msgpack.txt|	msgpack utilities
-|pi_netrw.txt|		Reading and writing files over a network
 |pi_paren.txt|		Highlight matching parens
 |pi_spec.txt|		Filetype plugin to work with rpm spec files
 |pi_tar.txt|		Tar file explorer
 |pi_zip.txt|		Zip archive explorer
+|netrw|			Reading and writing files over a network
 
 Local additions ~
 							*local-additions*
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 0256707420..b814b3be78 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -786,8 +786,7 @@ tag		char	      note action in Normal mode	~
 |gu|		gu{motion}	2  make Nmove text lowercase
 |gv|		gv		   reselect the previous Visual area
 |gw|		gw{motion}	2  format Nmove text and keep cursor
-|netrw-gx|	gx		   execute application for file name under the
-				   cursor (only with |netrw| plugin)
+|gx|		gx		   execute application for filepath at cursor
 |g@|		g@{motion}	   call 'operatorfunc'
 |g~|		g~{motion}	2  swap case for Nmove text
 |g<Down>|	g<Down>		1  same as "gj"
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index a39f475b4b..b77339a325 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -643,8 +643,8 @@ Also see the 'infercase' option if you want to adjust the case of the match.
 
 When inserting a selected candidate word from the |popup-menu|, the part of
 the candidate word that does not match the query is highlighted using
-|hl-ComplMatchIns|. If fuzzy is enabled in 'completopt', highlighting will not
-be applied.
+|hl-ComplMatchIns|. If fuzzy is enabled in 'completeopt', highlighting will
+not be applied.
 
 							*complete_CTRL-E*
 When completion is active you can use CTRL-E to stop it and go back to the
diff --git a/runtime/doc/lua-bit.txt b/runtime/doc/lua-bit.txt
index 4c47010113..dde235d141 100644
--- a/runtime/doc/lua-bit.txt
+++ b/runtime/doc/lua-bit.txt
@@ -86,19 +86,17 @@ Bit operations
 y = bit.tobit(x)                                                   *bit.tobit()*
     Normalizes a number to the numeric range for bit operations and returns
     it. This function is usually not needed since all bit operations already
-    normalize all of their input arguments. Check the |luabit-semantics| for
-    details.
+    normalize all of their input arguments. See |lua-bit-semantics|.
 
     Example: >lua
-        print(0xffffffff)                --> 4294967295 (*)
+        print(0xffffffff)                --> 4294967295 (see Note)
         print(bit.tobit(0xffffffff))     --> -1
         printx(bit.tobit(0xffffffff))    --> 0xffffffff
         print(bit.tobit(0xffffffff + 1)) --> 0
         print(bit.tobit(2^40 + 1234))    --> 1234
 <
-    (*) See the treatment of |lua-bit-hex-literals| for an explanation why the
-    printed numbers in the first two lines differ (if your Lua installation
-    uses a double number type).
+    Note: |lua-bit-hex-literals| explains why the numbers printed in the first
+    two lines differ (if your Lua installation uses a double number type).
 
 y = bit.tohex(x [,n])                                           *bit.tohex()*
     Converts its first argument to a hex string. The number of hex digits is
@@ -369,7 +367,7 @@ strongly advised not to rely on undefined or implementation-defined behavior.
         - Non-integral numbers may be rounded or truncated in an
           implementation-defined way. This means the result could differ between
           different BitOp versions, different Lua VMs, on different platforms or
-          even between interpreted vs. compiled code (as in |LuaJIT|). Avoid
+          even between interpreted vs. compiled code (as in LuaJIT). Avoid
           passing fractional numbers to bitwise functions. Use `math.floor()` or
           `math.ceil()` to get defined behavior.
 - Lua provides auto-coercion of string arguments to numbers by default. This
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 4fc9e8e245..e42fb4f9e4 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -4505,7 +4505,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 		set path=,,
 <	- A directory name may end in a ':' or '/'.
 	- Environment variables are expanded |:set_env|.
-	- When using |netrw.vim| URLs can be used.  For example, adding
+	- When using |netrw| URLs can be used.  For example, adding
 	  "https://www.vim.org" will make ":find index.html" work.
 	- Search upwards and downwards in a directory tree using "*", "**" and
 	  ";".  See |file-searching| for info and syntax.
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index b4c7a5f96a..00486a49db 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -4816,7 +4816,7 @@ interface and syntax highlighting. In rough order of importance, these are
 - standard syntax |group-name|s (in addition, syntax files can define
   language-specific groups, which are prefixed with the language name)
 - |diagnostic-highlights|
-- |tree-sitter-highlight-groups|
+- |treesitter-highlight-groups|
 - |lsp-semantic-highlight| groups
 - |lsp-highlight| of symbols and references
 
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index f0172c36e5..31335b4fbb 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -789,7 +789,7 @@ must handle.
 		"" (empty)	Unknown (consider a |feature-request|)
 		"bufwrite"	|:write| message
 		"confirm"	Message preceding a prompt (|:confirm|,
-				|confirm()|, |inputlist()|, |z=,|, …)
+				|confirm()|, |inputlist()|, |z=|, …)
 		"emsg"		Error (|errors|, internal error, |:throw|, …)
 		"echo"		|:echo| message
 		"echomsg"	|:echomsg| message
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 1519beec50..59e65b0585 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -4640,7 +4640,7 @@ vim.go.pm = vim.go.patchmode
 --- ```
 --- - A directory name may end in a ':' or '/'.
 --- - Environment variables are expanded `:set_env`.
---- - When using `netrw.vim` URLs can be used.  For example, adding
+--- - When using `netrw` URLs can be used.  For example, adding
 ---   "https://www.vim.org" will make ":find index.html" work.
 --- - Search upwards and downwards in a directory tree using "*", "**" and
 ---   ";".  See `file-searching` for info and syntax.
diff --git a/scripts/lintdoc.lua b/scripts/lintdoc.lua
index 78cf9fed72..d246c51176 100755
--- a/scripts/lintdoc.lua
+++ b/scripts/lintdoc.lua
@@ -10,8 +10,10 @@
 
 print('Running lintdoc ...')
 
--- gen_help_html requires :helptags to be generated on $VIMRUNTIME/doc
--- :helptags checks for duplicate tags.
+-- gen_help_html.lua requires helptags to be generated in $VIMRUNTIME/doc.
+-- :helptags also checks for duplicate tags.
+-- 🤢 Load netrw so its tags are generated by :helptags.
+vim.cmd [[ packadd netrw ]]
 vim.cmd [[ helptags ALL ]]
 
 require('src.gen.gen_help_html').run_validate()
diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua
index d4766d84a1..0d98d9e1b1 100644
--- a/src/gen/gen_help_html.lua
+++ b/src/gen/gen_help_html.lua
@@ -778,6 +778,7 @@ local function parse_buf(fname, text, parser_path)
     vim.treesitter.language.add('vimdoc', { path = parser_path })
   end
   local lang_tree = assert(vim.treesitter.get_parser(buf, nil, { error = false }))
+  lang_tree:parse()
   return lang_tree, buf
 end
 
@@ -1397,6 +1398,9 @@ function M.validate(help_dir, include, parser_path)
   local files_to_errors = {} ---@type table<string, string[]>
   ensure_runtimepath()
   tagmap = get_helptags(vim.fs.normalize(help_dir))
+  --- XXX: Append tags from netrw, until we remove it...
+  local netrwtags = get_helptags(vim.fs.normalize('$VIMRUNTIME/pack/dist/opt/netrw/doc/'))
+  tagmap = vim.tbl_extend('keep', tagmap, netrwtags)
   helpfiles = get_helpfiles(help_dir, include)
   parser_path = parser_path and vim.fs.normalize(parser_path) or nil
 
@@ -1424,7 +1428,7 @@ function M.validate(help_dir, include, parser_path)
   }
 end
 
---- Validates vimdoc files on $VIMRUNTIME. and print human-readable error messages if fails.
+--- Validates vimdoc files in $VIMRUNTIME, and prints error messages on failure.
 ---
 --- If this fails, try these steps (in order):
 --- 1. Fix/cleanup the :help docs.
@@ -1464,7 +1468,7 @@ function M.test_gen(help_dir)
   print('doc path = ' .. vim.uv.fs_realpath(help_dir))
 
   -- Because gen() is slow (~30s), this test is limited to a few files.
-  local input = { 'help.txt', 'index.txt', 'nvim.txt' }
+  local input = { 'api.txt', 'index.txt', 'nvim.txt' }
   local rv = M.gen(help_dir, tmpdir, input)
   eq(#input, #rv.helpfiles)
   eq(0, rv.err_count, 'parse errors in :help docs')
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index 66244a64ac..49de8b92ef 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -6236,7 +6236,7 @@ local options = {
         	set path=,,
         <	- A directory name may end in a ':' or '/'.
         - Environment variables are expanded |:set_env|.
-        - When using |netrw.vim| URLs can be used.  For example, adding
+        - When using |netrw| URLs can be used.  For example, adding
           "https://www.vim.org" will make ":find index.html" work.
         - Search upwards and downwards in a directory tree using "*", "**" and
           ";".  See |file-searching| for info and syntax.