perf: add fast path to vim.validate (#28977)

For many small/simple functions (like those found in shared.lua), the
runtime of vim.validate can far exceed the runtime of the function
itself. Add an "overload" to vim.validate that uses a simple assertion
pattern, rather than parsing a full "validation spec".

1 files changed, 20 insertions, 1 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 64a3014388..fd0cd3252f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2366,7 +2366,26 @@ vim.trim({s})                                                     *vim.trim()*
       • https://www.lua.org/pil/20.2.html
 
 vim.validate({opt})                                           *vim.validate()*
-    Validates a parameter specification (types and values). Specs are
+    Validate function arguments.
+
+    This function has two valid forms:
+    1. vim.validate(name: str, value: any, type: string, optional?: bool)
+    2. vim.validate(spec: table)
+
+    Form 1 validates that argument {name} with value {value} has the type
+    {type}. {type} must be a value returned by |lua-type()|. If {optional} is
+    true, then {value} may be null. This form is significantly faster and
+    should be preferred for simple cases.
+
+    Example: >lua
+        function vim.startswith(s, prefix)
+          vim.validate('s', s, 'string')
+          vim.validate('prefix', prefix, 'string')
+          ...
+        end
+<
+
+    Form 2 validates a parameter specification (types and values). Specs are
     evaluated in alphanumeric order, until the first failure.
 
     Usage example: >lua