docs: specify that uv.spawn can throw an error

[telemachus]

I know that this may seem too trivial to add, but it would have helped me, so maybe it will help others.

I came to uv.spawn (and luv) via neovim. In that context, I was using an internal API (vim.system) that depends on uv.spawn. It wasn't clear to me what vim.system or uv.spawn did if the process entirely failed to start, and this change lets the reader know that uv.spawn throws an error in that case rather than returning an error code of some kind.

[Bilal2453]

Could you please verify that uv.spawn is the one throwing the error? I believe it shouldn't, on failure it will return the so called failure tuple, a nil value followed by two string returns instead of throwing an error.

[zeertzjq]

It's not. The error is thrown here at https://github.com/neovim/neovim/blob/7a5effb0f95e295c265fe09e7414d859a6d79657/runtime/lua/vim/_system.lua#L241:

local function spawn(cmd, opts, on_exit, on_error)
  local handle, pid_or_err = uv.spawn(cmd, opts, on_exit)
  if not handle then
    on_error()
    error(pid_or_err)
  end
  return handle, pid_or_err --[[@as integer]]
end

[Bilal2453]

Sadly then, I don't think we can change the docs here, saying it would throw an error will be very confusing for anyone using luv directly.

Also see the luv docs for pseudo types and the fail tuple.

[telemachus]

@Bilal2453 Sorry to waste your time: I was confused. I'll close this now.

[Bilal2453]

No worries!