From d249e18bbf3454088eddf400b13b353b3ff6d91c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mathias=20Fu=C3=9Fenegger?=
 <mfussenegger@users.noreply.github.com>
Date: Thu, 18 Nov 2021 21:12:21 +0100
Subject: [PATCH] fix(uri): use valid EmmyLua annotations (#16359)

See:

- https://emmylua.github.io/annotations/param.html
- https://emmylua.github.io/annotations/return.html
---
 runtime/doc/lua.txt     | 22 ++++++++++------------
 runtime/lua/vim/uri.lua | 28 ++++++++++++----------------
 2 files changed, 22 insertions(+), 28 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index ef2d87949d..906da31d3a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1658,40 +1658,38 @@ uri_from_bufnr({bufnr})                                 *vim.uri_from_bufnr()*
                 Get a URI from a bufnr
 
                 Parameters: ~
-                    {bufnr}  (number): Buffer number
+                    {bufnr}  number
 
                 Return: ~
-                    URI
+                    string URI
 
 uri_from_fname({path})                                  *vim.uri_from_fname()*
                 Get a URI from a file path.
 
                 Parameters: ~
-                    {path}  (string): Path to file
+                    {path}  string Path to file
 
                 Return: ~
-                    URI
+                    string URI
 
 uri_to_bufnr({uri})                                       *vim.uri_to_bufnr()*
-                Return or create a buffer for a uri.
+                Get the buffer for a uri. Creates a new unloaded buffer if no
+                buffer for the uri already exists.
 
                 Parameters: ~
-                    {uri}  (string): The URI
+                    {uri}  string
 
                 Return: ~
-                    bufnr.
-
-                Note:
-                    Creates buffer but does not load it
+                    number bufnr
 
 uri_to_fname({uri})                                       *vim.uri_to_fname()*
                 Get a filename from a URI
 
                 Parameters: ~
-                    {uri}  (string): The URI
+                    {uri}  string
 
                 Return: ~
-                    Filename
+                    string filename or unchanged URI for non-file URIs
 
 
 ==============================================================================
diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 5d8d4fa169..d08d2a3ee3 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -56,8 +56,8 @@ local function is_windows_file_uri(uri)
 end
 
 --- Get a URI from a file path.
----@param path (string): Path to file
----@return URI
+---@param path string Path to file
+---@return string URI
 local function uri_from_fname(path)
   local volume_path, fname = path:match("^([a-zA-Z]:)(.*)")
   local is_windows = volume_path ~= nil
@@ -78,8 +78,8 @@ local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):.*'
 local WINDOWS_URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):[a-zA-Z]:.*'
 
 --- Get a URI from a bufnr
----@param bufnr (number): Buffer number
----@return URI
+---@param bufnr number
+---@return string URI
 local function uri_from_bufnr(bufnr)
   local fname = vim.api.nvim_buf_get_name(bufnr)
   local volume_path = fname:match("^([a-zA-Z]:).*")
@@ -99,8 +99,8 @@ local function uri_from_bufnr(bufnr)
 end
 
 --- Get a filename from a URI
----@param uri (string): The URI
----@return Filename
+---@param uri string
+---@return string filename or unchanged URI for non-file URIs
 local function uri_to_fname(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme ~= 'file' then
@@ -117,17 +117,13 @@ local function uri_to_fname(uri)
   return uri
 end
 
---- Return or create a buffer for a uri.
----@param uri (string): The URI
----@return bufnr.
----@note Creates buffer but does not load it
+--- Get the buffer for a uri.
+--- Creates a new unloaded buffer if no buffer for the uri already exists.
+--
+---@param uri string
+---@return number bufnr
 local function uri_to_bufnr(uri)
-  local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
-  if scheme == 'file' then
-    return vim.fn.bufadd(uri_to_fname(uri))
-  else
-    return vim.fn.bufadd(uri)
-  end
+  return vim.fn.bufadd(uri_to_fname(uri))
 end
 
 return {