fix(filetype): call on_detect before setting buffer filetype

The on_detect functions returned by filetype.lua set buffer local
variables which are often used by filetype plugins. For example, the
on_detect function for shell buffers sets variables such as b:is_bash or
b:is_sh, which are used by the sh ftplugin.

When called after setting the buffer's filetype, these variables cannot
be used by the ftplugin (because they are not yet defined). Instead,
call on_detect before setting the buffer filetype so that any buffer
variables set by on_detect can be used in the ftplugin.

1 files changed, 2 insertions, 1 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 08022c3ed6..b4ca88251e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2600,7 +2600,8 @@ vim.filetype.add({filetypes})                             *vim.filetype.add()*
     matched pattern, if any) and should return a string that will be used as
     the buffer's filetype. Optionally, the function can return a second
     function value which, when called, modifies the state of the buffer. This
-    can be used to, for example, set filetype-specific buffer variables.
+    can be used to, for example, set filetype-specific buffer variables. This
+    function will be called by Nvim before setting the buffer's filetype.
 
     Filename patterns can specify an optional priority to resolve cases when a
     file path matches multiple patterns. Higher priorities are matched first.