docs: adjust fswatch overflow message to mention docs with info

- Add :h fswatch-limitations that notifies user about default inotify
  limitations on linux and how to adjust them
- Check for Event queue overflow message from fswatch and refer user to
  new documentation

Signed-off-by: Tomas Slusny <slusnucky@gmail.com>

1 files changed, 10 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index e1e3f88a1d..135a1b42de 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -530,6 +530,16 @@ Example: File-change detection                                    *watch-file*
     vim.api.nvim_command(
       "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))")
 <
+                                                         *fswatch-limitations*
+When on Linux and using fswatch, you may need to increase the maximum number
+of `inotify` watches and queued events as the default limit can be too low. To
+increase the limit, run: >sh
+    sysctl fs.inotify.max_user_watches=100000
+    sysctl fs.inotify.max_queued_events=100000
+<
+This will increase the limit to 100000 watches and queued events. These lines
+can be added to `/etc/sysctl.conf` to make the changes persistent.
+
 Example: TCP echo-server                                          *tcp-server*
     1. Save this code to a file.
     2. Execute it with ":luafile %".