From 40ce8577977fcdce8ad76863c70eb522e4cefd4d Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 3 May 2024 03:20:03 -0700
Subject: fix(vim.ui)!: change open() to return `result|nil, errmsg|nil` #28612

reverts e0d92b9cc20b58179599f53dfa74ca821935a539 #28502

Problem:
`vim.ui.open()` has a `pcall()` like signature, under the assumption
that this is the Lua idiom for returning result-or-error. However, the
`result|nil, errmsg|nil` pattern:
- has precedent in:
  - `io.open`
  - `vim.uv` (`:help luv-error-handling`)
- has these advantages:
  - Can be used with `assert()`:
    ```
    local result, err = assert(foobar())
    ```
  - Allows LuaLS to infer the type of `result`:
    ```
    local result, err = foobar()
    if err then
      ...
    elseif result then
      ...
    end
    ```

Solution:
- Revert to the `result|nil, errmsg|nil` pattern.
- Document the pattern in our guidelines.
---
 runtime/doc/develop.txt | 5 +++++
 runtime/doc/lua.txt     | 8 ++++----
 runtime/doc/news.txt    | 2 +-
 3 files changed, 10 insertions(+), 5 deletions(-)

(limited to 'runtime/doc')

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index b843988b94..f2eef7b131 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -309,6 +309,11 @@ See also |dev-naming|.
   - return iterable instead of table
   - mimic the pairs() or ipairs() interface if the function is intended to be
     used in a "for" loop.
+  - when a result-or-error interface is needed, return `result|nil, errmsg|nil`: >
+    ---@return Foo|nil # Result object, or nil if not found.
+    ---@return nil|string # Error message on failure, or nil on success.
+<
+    - Examples: |vim.ui.open()| |io.open()| |luv-error-handling|
 
 Interface conventions ~
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 2b1d20feda..4f538f52ab 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2551,8 +2551,8 @@ vim.ui.open({path})                                            *vim.ui.open()*
         vim.ui.open("https://neovim.io/")
         vim.ui.open("~/path/to/file")
         -- Synchronous (wait until the process exits).
-        local ok, cmd = vim.ui.open("$VIMRUNTIME")
-        if ok then
+        local cmd, err = vim.ui.open("$VIMRUNTIME")
+        if cmd then
           cmd:wait()
         end
 <
@@ -2561,8 +2561,8 @@ vim.ui.open({path})                                            *vim.ui.open()*
       • {path}  (`string`) Path or URL to open
 
     Return (multiple): ~
-        (`boolean`) false if command not found, else true.
-        (`vim.SystemObj|string`) Command object, or error message on failure
+        (`vim.SystemObj?`) Command object, or nil if not found.
+        (`string?`) Error message on failure, or nil on success.
 
     See also: ~
       • |vim.system()|
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 78d5560878..3886dbdfb0 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -163,7 +163,7 @@ cycle (Nvim HEAD, the "master" branch).
 
 • Renamed vim.tbl_isarray() to vim.isarray().
 
-• Changed |vim.ui.open()| return-signature to match pcall() convention.
+• Changed |vim.ui.open()| return-signature to match `result|nil, errormsg|nil` convention.
 
 • Renamed Iter:nextback() to Iter:pop()
 
-- 
cgit