docs(filetype): consolidate comments in dev_vimpatch.txt

1 files changed, 32 insertions, 19 deletions

diff --git a/runtime/doc/dev_vimpatch.txt b/runtime/doc/dev_vimpatch.txt
index a36b2a613b..9a2380b162 100644
--- a/runtime/doc/dev_vimpatch.txt
+++ b/runtime/doc/dev_vimpatch.txt
@@ -308,41 +308,54 @@ used in new documentation:
 FILETYPE DETECTION                 *dev-vimpatch-filetype*
 
 Nvim's filetype detection behavior matches Vim, but is implemented as part of
-|vim.filetype| (see $VIMRUNTIME/lua/vim/filetype.lua).
+|vim.filetype| (see `$VIMRUNTIME/lua/vim/filetype.lua`). The logic is encoded in
+three tables, listed in order of precedence (the first match is returned):
+1. `filename` for literal full path or basename lookup;
+2. `pattern` for matching filenames or paths against |lua-patterns|, optimized
+   for fast lookup;
+3. `extension` for literal extension lookup.
 
-Prefer explicit filenames/extensions over patterns, especially for case
+Logic that requires checking file contents or buffer variables is implemented
+in `$VIMRUNTIME/lua/vim/filetype/detect.lua`.
+
+When porting filetype patches from Vim, keep the following in mind:
+
+Prefer explicit filenames or extensions over patterns, especially for case
 insensitive matches (see https://github.com/neovim/neovim/pull/29800): >
     "*[mM]akefile" regex -> "makefile", "Makefile" filenames
     "*.js\c"       regex -> "js", "jS", "Js", "jS" extensions
 
 Pattern matching has several differences:
-- It is done using explicit Lua patterns (without implicit anchoring) instead
+- It is done using explicit Lua patterns without implicit anchoring instead
   of Vim regexes: >
     "*/debian/changelog" -> "/debian/changelog$"
     "*/bind/db.*"        -> "/bind/db%."
 <
 - Filetype patterns are grouped by their parent pattern to improve matching
-  performance. For this to work properly, parent pattern should:
-    - Match at least the same set of strings as filetype patterns inside it.
-      But not too much more.
-    - Be fast to match.
+  performance: If the parent pattern does not match, skip testing all child
+  patterns. Note that unlike leaf patterns, parent patterns do not have
+  special matching behaviour if they contain a `/`.
 
   When adding a new filetype with pattern matching, consider the following:
   - If there is already a group with appropriate parent pattern, use it.
-  - If there can be a fast and specific enough pattern to group at least
-    3 filetype patterns, add it as a separate grouped entry.
+  - If there can be a fast and specific enough pattern to group at least 3
+    filetype patterns, add it as a separate grouped entry.
 
-    Good new parent pattern should be:
-      - Fast. Good rule of thumb is that it should be a short explicit string
-        (i.e. no quantifiers or character sets).
-      - Specific. Good rules of thumb (from best to worst):
-          - Full directory name (like "/etc/", "/log/").
-          - Part of a rare enough directory name (like "/conf", "git/").
-          - String reasonably rarely used in real full paths (like "nginx").
+  New parent patterns should be
+  - fast: rule of thumb is that it should be a short explicit string
+  (i.e. no quantifiers or character sets);
+  - specific: rules of thumb, in order:
+    - full directory name (e.g., `"/etc/"`, `"/log/"`);
+    - part of a rare enough directory name (e.g., `"/conf"`, `"git/"`);
+    - string rarely used in real full paths (e.g., `"nginx"`).
 
   Example:
-  - Filetype pattern: ".*/etc/a2ps/.*%.cfg"
-  - Good parent: "/etc/"; "%.cfg$"
-  - Bad parent: "%." - fast, not specific; "/a2ps/.*%." - slow, specific
+  - Filetype pattern: `".*/etc/a2ps/.*%.cfg"`
+  - Good parents: `"/etc/"` or `"%.cfg$"`
+  - Bad parents: `"%."` (fast but not specific) or `"/a2ps/.*%."` (specific
+    but slow)
+
+  When modifying an existing regular pattern, make sure that it still fits its
+  group.
 
 vim:tw=78:ts=8:noet:ft=help:norl: