From 4a2618c8174eabb59a713cce6ae94a5ca592aeb3 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Mon, 14 Sep 2020 09:12:17 -0400
Subject: [PATCH] doc: Add docs for uri functions (#12887)

---
 runtime/doc/lua.txt     | 42 +++++++++++++++++++++++++++++++++++++++++
 runtime/lua/vim/uri.lua | 20 +++++++++++++++++++-
 scripts/gen_vimdoc.py   |  3 +++
 3 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index a60153d65f..477e70a9ae 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1567,4 +1567,46 @@ validate({opt})                                               *vim.validate()*
                               • msg: (optional) error string if validation
                                 fails
 
+
+==============================================================================
+Lua module: uri                                                      *lua-uri*
+
+uri_from_bufnr({bufnr})                                 *vim.uri_from_bufnr()*
+                Get a URI from a bufnr
+
+                Parameters: ~
+                    {bufnr}  (number): Buffer number
+
+                Return: ~
+                    URI
+
+uri_from_fname({path})                                  *vim.uri_from_fname()*
+                Get a URI from a file path.
+
+                Parameters: ~
+                    {path}  (string): Path to file
+
+                Return: ~
+                    URI
+
+uri_to_bufnr({uri})                                       *vim.uri_to_bufnr()*
+                Return or create a buffer for a uri.
+
+                Parameters: ~
+                    {uri}  (string): The URI
+
+                Return: ~
+                    bufnr.
+                Note:
+                    Creates buffer but does not load it
+
+uri_to_fname({uri})                                       *vim.uri_to_fname()*
+                Get a filename from a URI
+
+                Parameters: ~
+                    {uri}  (string): The URI
+
+                Return: ~
+                    Filename
+
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 9c3535c676..f1a12c72ec 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -7,6 +7,9 @@
 local uri_decode
 do
   local schar = string.char
+
+  --- Convert hex to char
+  --@private
   local function hex_to_char(hex)
     return schar(tonumber(hex, 16))
   end
@@ -34,6 +37,8 @@ do
   else
     tohex = function(b) return string.format("%02x", b) end
   end
+
+  --@private
   local function percent_encode_char(char)
     return "%"..tohex(sbyte(char), 2)
   end
@@ -45,10 +50,14 @@ do
 end
 
 
+--@private
 local function is_windows_file_uri(uri)
   return uri:match('^file:///[a-zA-Z]:') ~= nil
 end
 
+--- Get a URI from a file path.
+--@param path (string): Path to file
+--@return URI
 local function uri_from_fname(path)
   local volume_path, fname = path:match("^([a-zA-Z]:)(.*)")
   local is_windows = volume_path ~= nil
@@ -67,6 +76,9 @@ end
 
 local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*)://.*'
 
+--- Get a URI from a bufnr
+--@param bufnr (number): Buffer number
+--@return URI
 local function uri_from_bufnr(bufnr)
   local fname = vim.api.nvim_buf_get_name(bufnr)
   local scheme = fname:match(URI_SCHEME_PATTERN)
@@ -77,6 +89,9 @@ local function uri_from_bufnr(bufnr)
   end
 end
 
+--- Get a filename from a URI
+--@param uri (string): The URI
+--@return Filename
 local function uri_to_fname(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme ~= 'file' then
@@ -93,7 +108,10 @@ local function uri_to_fname(uri)
   return uri
 end
 
--- Return or create a buffer for a uri.
+--- Return or create a buffer for a uri.
+--@param uri (string): The URI
+--@return bufnr.
+--@note Creates buffer but does not load it
 local function uri_to_bufnr(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme == 'file' then
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index f754452c02..c42b568220 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -113,10 +113,12 @@ CONFIG = {
         'section_order': [
             'vim.lua',
             'shared.lua',
+            'uri.lua',
         ],
         'files': ' '.join([
             os.path.join(base_dir, 'src/nvim/lua/vim.lua'),
             os.path.join(base_dir, 'runtime/lua/vim/shared.lua'),
+            os.path.join(base_dir, 'runtime/lua/vim/uri.lua'),
         ]),
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
@@ -129,6 +131,7 @@ CONFIG = {
         'module_override': {
             # `shared` functions are exposed on the `vim` module.
             'shared': 'vim',
+            'uri': 'vim',
         },
         'append_only': [
             'shared.lua',