fix(vim.ui): open() may wait indefinitely #28325

Problem:
vim.ui.open "locks up" Nvim if the spawned process does not terminate. #27986

Solution:
- Change `vim.ui.open()`:
    - Do not call `wait()`.
    - Return a `SystemObj`. The caller can decide if it wants to `wait()`.
- Change `gx` to `wait()` only a short time.
    - Allows `gx` to show a message if the command fails, without the
      risk of waiting forever.

1 files changed, 8 insertions, 2 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index d967e2b313..c760e762ee 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1812,6 +1812,7 @@ vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
 
     Return: ~
         (`vim.SystemObj`) Object with the fields:
+        • cmd (string[]) Command name and args
         • pid (integer) Process ID
         • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the
           process to complete. Upon timeout the process is sent the KILL
@@ -2568,16 +2569,21 @@ vim.ui.open({path})                                            *vim.ui.open()*
     Expands "~/" and environment variables in filesystem paths.
 
     Examples: >lua
+        -- Asynchronous.
         vim.ui.open("https://neovim.io/")
         vim.ui.open("~/path/to/file")
-        vim.ui.open("$VIMRUNTIME")
+        -- Synchronous (wait until the process exits).
+        local cmd, err = vim.ui.open("$VIMRUNTIME")
+        if cmd then
+          cmd:wait()
+        end
 <
 
     Parameters: ~
       • {path}  (`string`) Path or URL to open
 
     Return (multiple): ~
-        (`vim.SystemCompleted?`) Command result, or nil if not found.
+        (`vim.SystemObj?`) Command object, or nil if not found.
         (`string?`) Error message on failure
 
     See also: ~