refactor(vim.version): cleanup

- version.cmp(): assert valid version
- add test for loading vim.version (the other tests use shared.lua in
  the test runner)
- reduce test scopes, reword test descriptions

2 files changed, 23 insertions, 29 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 3c48cd37a6..697cd86e8a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2501,12 +2501,12 @@ trust({opts})                                             *vim.secure.trust()*
 ==============================================================================
 Lua module: version                                              *lua-version*
 
-cmp({v1}, {v2}, {opts})                                        *version.cmp()*
+cmp({v1}, {v2}, {opts})                                    *vim.version.cmp()*
     Compares two strings ( `v1` and `v2` ) in semver format.
 
     Parameters: ~
       • {v1}    (string) Version.
-      • {v2}    (string) Version to be compared with v1.
+      • {v2}    (string) Version to compare with v1.
       • {opts}  (table|nil) Optional keyword arguments:
                 • strict (boolean): see `semver.parse` for details. Defaults
                   to false.
@@ -2514,59 +2514,54 @@ cmp({v1}, {v2}, {opts})                                        *version.cmp()*
     Return: ~
         (integer) `-1` if `v1 < v2`, `0` if `v1 == v2`, `1` if `v1 > v2`.
 
-eq({version_1}, {version_2})                                    *version.eq()*
+eq({v1}, {v2})                                              *vim.version.eq()*
     Returns `true` if `v1` are `v2` are equal versions.
 
     Parameters: ~
-      • {version_1}  (string)
-      • {version_2}  (string)
+      • {v1}  (string)
+      • {v2}  (string)
 
     Return: ~
         (boolean)
 
-gt({version_1}, {version_2})                                    *version.gt()*
+gt({v1}, {v2})                                              *vim.version.gt()*
     Returns `true` if `v1` is greater than `v2` .
 
     Parameters: ~
-      • {version_1}  (string)
-      • {version_2}  (string)
+      • {v1}  (string)
+      • {v2}  (string)
 
     Return: ~
         (boolean)
 
-lt({version_1}, {version_2})                                    *version.lt()*
+lt({v1}, {v2})                                              *vim.version.lt()*
     Returns `true` if `v1` is less than `v2` .
 
     Parameters: ~
-      • {version_1}  (string)
-      • {version_2}  (string)
+      • {v1}  (string)
+      • {v2}  (string)
 
     Return: ~
         (boolean)
 
-parse({version}, {opts})                                     *version.parse()*
-    Parses a semantically formatted version string into a table.
+parse({version}, {opts})                                 *vim.version.parse()*
+    Parses a semantic version string.
 
-    Supports leading "v" and leading and trailing whitespace in the version
-    string. e.g. `" v1.0.1-rc1+build.2"` , `"1.0.1-rc1+build.2"`,
-    `"v1.0.1-rc1+build.2"` and `"v1.0.1-rc1+build.2 "` will be parsed as:
+    Ignores leading "v" and surrounding whitespace, e.g. "
+    v1.0.1-rc1+build.2", "1.0.1-rc1+build.2", "v1.0.1-rc1+build.2" and
+    "v1.0.1-rc1+build.2 " are all parsed as: >
 
-    { major = 1, minor = 0, patch = 1, prerelease = 'rc1 , build = 'build.2' }`
+       { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
+<
 
     Parameters: ~
       • {version}  (string) Version string to be parsed.
       • {opts}     (table|nil) Optional keyword arguments:
-                   • strict (boolean): when set to `true` an error will be
-                     thrown for version strings that do not conform to the
-                     semver specification (v2.0.0) (see
-                     semver.org/spec/v2.0.0.html for details). This means that
-                     `semver.parse('v1.2)` will throw an error. When set to
-                     `false`, `semver.parse('v1.2)` will coerce 'v1.2' to
-                     'v1.2.0' and return the table: `{ major = 1, minor = 2,
-                     patch = 0 }`. Defaults to false.
+                   • strict (boolean): Default false. If `true` , no coercion is attempted on input not strictly
+                     conforming to semver v2.0.0 ( https://semver.org/spec/v2.0.0.html ). E.g. `parse("v1.2")` returns nil.
 
     Return: ~
         (table|nil) parsed_version Parsed version table or `nil` if `version`
-        is not valid.
+        is invalid.
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index b5cb975066..28fdaa770d 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -55,9 +55,8 @@ NEW FEATURES                                                    *news-features*
 
 The following new APIs or features were added.
 
-• Added |version.parse()|, |version.cmp()|, |version.lt()|, |version.eq()|
-  and |version.gt()| to |vim.version| for parsing and comparing version numbers
-  according to the semver specification, see |lua-version|.
+• Added |vim.version| for parsing and comparing version strings conforming to
+  the semver specification, see |lua-version|.
 
 • A new environment variable named NVIM_APPNAME enables configuring the
   directories where Neovim should find its configuration and state files. See