From f529bc74f9abfadeebcab76673bd03b6e74f82de Mon Sep 17 00:00:00 2001
From: Luis Calle <53507599+TheLeoP@users.noreply.github.com>
Date: Wed, 8 Apr 2026 10:38:27 -0500
Subject: [PATCH] docs: vim.range, vim.pos #38869

Problem:
`vim.Range` and `vim.Pos` have signature mismatches on the docs of some functions.

Solution:
Split the "module" functions from the "class" functions (just like it's done in other modules like `vim.version`) and regenerate the docs.

(cherry picked from commit c530fd8e752607f57b83854b74b029eabe8d57c6)
---
 runtime/doc/lua.txt       | 251 ++++++++++++++++++--------------------
 runtime/lua/vim/pos.lua   |  48 ++++----
 runtime/lua/vim/range.lua |  86 ++++++-------
 3 files changed, 181 insertions(+), 204 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 46407a63962..5f19501e8af 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -4280,28 +4280,53 @@ by |vim.Pos| objects.
       • {row}         (`integer`) 0-based byte index.
       • {col}         (`integer`) 0-based byte index.
       • {buf}         (`integer`) buffer handle.
-      • {to_lsp}      (`fun(pos: vim.Pos, position_encoding: lsp.PositionEncodingKind)`)
+      • {to_lsp}      (`fun(self: vim.Pos, position_encoding: lsp.PositionEncodingKind)`)
                       See |Pos:to_lsp()|.
-      • {lsp}         (`fun(buf: integer, pos: lsp.Position, position_encoding: lsp.PositionEncodingKind)`)
-                      See |Pos:lsp()|.
-      • {to_cursor}   (`fun(pos: vim.Pos): integer, integer`) See
+      • {to_cursor}   (`fun(self: vim.Pos): integer, integer`) See
                       |Pos:to_cursor()|.
-      • {cursor}      (`fun(buf: integer, pos: [integer, integer])`) See
-                      |Pos:cursor()|.
-      • {to_extmark}  (`fun(pos: vim.Pos): integer, integer`) See
+      • {to_extmark}  (`fun(self: vim.Pos): integer, integer`) See
                       |Pos:to_extmark()|.
-      • {extmark}     (`fun(buf: integer, row: integer, col: integer)`) See
-                      |Pos:extmark()|.
 
 
-Pos:cursor({buf}, {pos})                                        *Pos:cursor()*
+Pos:to_cursor()                                              *Pos:to_cursor()*
+    Converts |vim.Pos| to cursor position (see |api-indexing|).
+
+    Return (multiple): ~
+        (`integer`)
+        (`integer`)
+
+Pos:to_extmark()                                            *Pos:to_extmark()*
+    Converts |vim.Pos| to extmark position (see |api-indexing|).
+
+    Return (multiple): ~
+        (`integer`)
+        (`integer`)
+
+Pos:to_lsp({position_encoding})                                 *Pos:to_lsp()*
+    Converts |vim.Pos| to `lsp.Position`.
+
+    Example: >lua
+        local buf = vim.api.nvim_get_current_buf()
+        local pos = vim.pos(buf, 3, 5)
+
+        -- Convert to LSP position, you can call it in a method style.
+        local lsp_pos = pos:lsp('utf-16')
+<
+
+    Parameters: ~
+      • {position_encoding}  (`lsp.PositionEncodingKind`)
+
+vim.pos.cursor({buf}, {pos})                                *vim.pos.cursor()*
     Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 
     Parameters: ~
       • {buf}  (`integer`)
       • {pos}  (`[integer, integer]`)
 
-Pos:extmark({buf}, {row}, {col})                               *Pos:extmark()*
+    Return: ~
+        (`vim.Pos`) See |vim.Pos|.
+
+vim.pos.extmark({buf}, {row}, {col})                       *vim.pos.extmark()*
     Creates a new |vim.Pos| from extmark position (see |api-indexing|).
 
     Parameters: ~
@@ -4309,7 +4334,10 @@ Pos:extmark({buf}, {row}, {col})                               *Pos:extmark()*
       • {row}  (`integer`)
       • {col}  (`integer`)
 
-Pos:lsp({buf}, {pos}, {position_encoding})                         *Pos:lsp()*
+    Return: ~
+        (`vim.Pos`) See |vim.Pos|.
+
+vim.pos.lsp({buf}, {pos}, {position_encoding})                 *vim.pos.lsp()*
     Creates a new |vim.Pos| from `lsp.Position`.
 
     Example: >lua
@@ -4327,40 +4355,8 @@ Pos:lsp({buf}, {pos}, {position_encoding})                         *Pos:lsp()*
       • {pos}                (`lsp.Position`)
       • {position_encoding}  (`lsp.PositionEncodingKind`)
 
-Pos:to_cursor({pos})                                         *Pos:to_cursor()*
-    Converts |vim.Pos| to cursor position (see |api-indexing|).
-
-    Parameters: ~
-      • {pos}  (`vim.Pos`) See |vim.Pos|.
-
-    Return (multiple): ~
-        (`integer`)
-        (`integer`)
-
-Pos:to_extmark({pos})                                       *Pos:to_extmark()*
-    Converts |vim.Pos| to extmark position (see |api-indexing|).
-
-    Parameters: ~
-      • {pos}  (`vim.Pos`) See |vim.Pos|.
-
-    Return (multiple): ~
-        (`integer`)
-        (`integer`)
-
-Pos:to_lsp({pos}, {position_encoding})                          *Pos:to_lsp()*
-    Converts |vim.Pos| to `lsp.Position`.
-
-    Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local pos = vim.pos(buf, 3, 5)
-
-        -- Convert to LSP position, you can call it in a method style.
-        local lsp_pos = pos:lsp('utf-16')
-<
-
-    Parameters: ~
-      • {pos}                (`vim.Pos`) See |vim.Pos|.
-      • {position_encoding}  (`lsp.PositionEncodingKind`)
+    Return: ~
+        (`vim.Pos`) See |vim.Pos|.
 
 
 ==============================================================================
@@ -4410,23 +4406,81 @@ Provides operations to compare, calculate, and convert ranges represented by
       • {buf}         (`integer`) Optional buffer handle.
       • {is_empty}    (`fun(self: vim.Range): boolean`) See
                       |Range:is_empty()|.
-      • {has}         (`fun(outer: vim.Range, inner: vim.Range|vim.Pos): boolean`)
+      • {has}         (`fun(self: vim.Range, inner: vim.Range|vim.Pos): boolean`)
                       See |Range:has()|.
-      • {intersect}   (`fun(r1: vim.Range, r2: vim.Range): vim.Range?`) See
+      • {intersect}   (`fun(self: vim.Range, r2: vim.Range): vim.Range?`) See
                       |Range:intersect()|.
-      • {to_lsp}      (`fun(range: vim.Range, position_encoding: lsp.PositionEncodingKind): lsp.Range`)
+      • {to_lsp}      (`fun(self: vim.Range, position_encoding: lsp.PositionEncodingKind): lsp.Range`)
                       See |Range:to_lsp()|.
-      • {lsp}         (`fun(buf: integer, range: lsp.Range, position_encoding: lsp.PositionEncodingKind)`)
-                      See |Range:lsp()|.
-      • {to_extmark}  (`fun(range: vim.Range)`) See |Range:to_extmark()|.
-      • {extmark}     (`fun(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer)`)
-                      See |Range:extmark()|.
-      • {to_cursor}   (`fun(range: vim.Range)`) See |Range:to_cursor()|.
-      • {cursor}      (`fun(buf: integer, start_pos: [integer, integer], end_pos: [integer, integer])`)
-                      See |Range:cursor()|.
+      • {to_extmark}  (`fun(self: vim.Range)`) See |Range:to_extmark()|.
+      • {to_cursor}   (`fun(self: vim.Range)`) See |Range:to_cursor()|.
 
 
-Range:cursor({buf}, {start_pos}, {end_pos})                   *Range:cursor()*
+Range:has({inner})                                               *Range:has()*
+    Checks whether range contains {inner} range or position.
+
+    Parameters: ~
+      • {inner}  (`vim.Range|vim.Pos`)
+
+    Return: ~
+        (`boolean`) `true` if range fully contains {inner} range or position.
+
+Range:intersect({r2})                                      *Range:intersect()*
+    Computes the common range shared by range and {r2}
+
+    Parameters: ~
+      • {r2}  (`vim.Range`) Second range to intersect. See |vim.Range|.
+
+    Return: ~
+        (`vim.Range?`) range that is present inside both range and `r2`. `nil`
+        if such range does not exist. See |vim.Range|.
+
+Range:is_empty()                                            *Range:is_empty()*
+    Checks whether the given range is empty; i.e., start >= end.
+
+    Return: ~
+        (`boolean`) `true` if the given range is empty
+
+Range:to_cursor()                                          *Range:to_cursor()*
+    Converts |vim.Range| to mark-like range (see |api-indexing|).
+
+    Example: >lua
+        local buf = vim.api.nvim_get_current_buf()
+        local range = vim.range(buf, 3, 5, 4, 0)
+
+        -- Convert to cursor range, you can call it in a method style.
+        local cursor_range = range:to_cursor()
+<
+
+Range:to_extmark()                                        *Range:to_extmark()*
+    Converts |vim.Range| to extmark range (see |api-indexing|).
+
+    Example: >lua
+        local buf = vim.api.nvim_get_current_buf()
+        local range = vim.range(buf, 3, 5, 4, 0)
+
+        -- Convert to extmark range, you can call it in a method style.
+        local extmark_range = range:to_extmark()
+<
+
+Range:to_lsp({position_encoding})                             *Range:to_lsp()*
+    Converts |vim.Range| to `lsp.Range`.
+
+    Example: >lua
+        local buf = vim.api.nvim_get_current_buf()
+        local range = vim.range(buf, 3, 5, 4, 0)
+
+        -- Convert to LSP range, you can call it in a method style.
+        local lsp_range = range:to_lsp('utf-16')
+<
+
+    Parameters: ~
+      • {position_encoding}  (`lsp.PositionEncodingKind`)
+
+    Return: ~
+        (`lsp.Range`)
+
+vim.range.cursor({buf}, {start_pos}, {end_pos})           *vim.range.cursor()*
     Creates a new |vim.Range| from mark-like range (see |api-indexing|).
 
     Example: >lua
@@ -4443,8 +4497,11 @@ Range:cursor({buf}, {start_pos}, {end_pos})                   *Range:cursor()*
       • {start_pos}  (`[integer, integer]`)
       • {end_pos}    (`[integer, integer]`)
 
-                                                             *Range:extmark()*
-Range:extmark({buf}, {start_row}, {start_col}, {end_row}, {end_col})
+    Return: ~
+        (`vim.Range`) See |vim.Range|.
+
+                                                         *vim.range.extmark()*
+vim.range.extmark({buf}, {start_row}, {start_col}, {end_row}, {end_col})
     Creates a new |vim.Range| from extmark range (see |api-indexing|).
 
     Example: >lua
@@ -4460,35 +4517,10 @@ Range:extmark({buf}, {start_row}, {start_col}, {end_row}, {end_col})
       • {end_row}    (`integer`)
       • {end_col}    (`integer`)
 
-Range:has({outer}, {inner})                                      *Range:has()*
-    Checks whether {outer} range contains {inner} range or position.
-
-    Parameters: ~
-      • {outer}  (`vim.Range`) See |vim.Range|.
-      • {inner}  (`vim.Range|vim.Pos`)
-
     Return: ~
-        (`boolean`) `true` if {outer} range fully contains {inner} range or
-        position.
+        (`vim.Range`) See |vim.Range|.
 
-Range:intersect({r1}, {r2})                                *Range:intersect()*
-    Computes the common range shared by the given ranges.
-
-    Parameters: ~
-      • {r1}  (`vim.Range`) First range to intersect. See |vim.Range|.
-      • {r2}  (`vim.Range`) Second range to intersect. See |vim.Range|.
-
-    Return: ~
-        (`vim.Range?`) range that is present inside both `r1` and `r2`. `nil`
-        if such range does not exist. See |vim.Range|.
-
-Range:is_empty()                                            *Range:is_empty()*
-    Checks whether the given range is empty; i.e., start >= end.
-
-    Return: ~
-        (`boolean`) `true` if the given range is empty
-
-Range:lsp({buf}, {range}, {position_encoding})                   *Range:lsp()*
+vim.range.lsp({buf}, {range}, {position_encoding})           *vim.range.lsp()*
     Creates a new |vim.Range| from `lsp.Range`.
 
     Example: >lua
@@ -4506,51 +4538,8 @@ Range:lsp({buf}, {range}, {position_encoding})                   *Range:lsp()*
       • {range}              (`lsp.Range`)
       • {position_encoding}  (`lsp.PositionEncodingKind`)
 
-Range:to_cursor({range})                                   *Range:to_cursor()*
-    Converts |vim.Range| to mark-like range (see |api-indexing|).
-
-    Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local range = vim.range(buf, 3, 5, 4, 0)
-
-        -- Convert to cursor range, you can call it in a method style.
-        local cursor_range = range:to_cursor()
-<
-
-    Parameters: ~
-      • {range}  (`vim.Range`) See |vim.Range|.
-
-Range:to_extmark({range})                                 *Range:to_extmark()*
-    Converts |vim.Range| to extmark range (see |api-indexing|).
-
-    Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local range = vim.range(buf, 3, 5, 4, 0)
-
-        -- Convert to extmark range, you can call it in a method style.
-        local extmark_range = range:to_extmark()
-<
-
-    Parameters: ~
-      • {range}  (`vim.Range`) See |vim.Range|.
-
-Range:to_lsp({range}, {position_encoding})                    *Range:to_lsp()*
-    Converts |vim.Range| to `lsp.Range`.
-
-    Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local range = vim.range(buf, 3, 5, 4, 0)
-
-        -- Convert to LSP range, you can call it in a method style.
-        local lsp_range = range:to_lsp('utf-16')
-<
-
-    Parameters: ~
-      • {range}              (`vim.Range`) See |vim.Range|.
-      • {position_encoding}  (`lsp.PositionEncodingKind`)
-
     Return: ~
-        (`lsp.Range`)
+        (`vim.Range`) See |vim.Range|.
 
 
 ==============================================================================
diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
index 4701aa5b1d0..718e2800e7d 100644
--- a/runtime/lua/vim/pos.lua
+++ b/runtime/lua/vim/pos.lua
@@ -6,6 +6,8 @@
 --- Provides operations to compare, calculate, and convert positions represented by |vim.Pos|
 --- objects.
 
+local M = {}
+
 local api = vim.api
 local validate = vim.validate
 
@@ -41,7 +43,8 @@ local validate = vim.validate
 ---@field private [3] integer underlying representation of buf
 local Pos = {}
 
----@private
+M._Pos = Pos
+
 ---@param pos vim.Pos
 ---@param key any
 function Pos.__index(pos, key)
@@ -97,17 +100,14 @@ local function cmp_pos(p1, p2)
   return -1
 end
 
----@private
 function Pos.__lt(...)
   return cmp_pos(...) == -1
 end
 
----@private
 function Pos.__le(...)
   return cmp_pos(...) ~= 1
 end
 
----@private
 function Pos.__eq(...)
   return cmp_pos(...) == 0
 end
@@ -129,13 +129,11 @@ end
 --- -- Convert to LSP position, you can call it in a method style.
 --- local lsp_pos = pos:lsp('utf-16')
 --- ```
----@param pos vim.Pos
 ---@param position_encoding lsp.PositionEncodingKind
-function Pos.to_lsp(pos, position_encoding)
-  validate('pos', pos, 'table')
+function Pos:to_lsp(position_encoding)
   validate('position_encoding', position_encoding, 'string')
 
-  local buf, row, col = pos.buf, pos.row, pos.col
+  local buf, row, col = self.buf, self.row, self.col
   -- When on the first character,
   -- we can ignore the difference between byte and character.
   if col > 0 then
@@ -161,7 +159,8 @@ end
 ---@param buf integer
 ---@param pos lsp.Position
 ---@param position_encoding lsp.PositionEncodingKind
-function Pos.lsp(buf, pos, position_encoding)
+---@return vim.Pos
+function M.lsp(buf, pos, position_encoding)
   validate('buf', buf, 'number')
   validate('pos', pos, 'table')
   validate('position_encoding', position_encoding, 'string')
@@ -179,30 +178,29 @@ function Pos.lsp(buf, pos, position_encoding)
 end
 
 --- Converts |vim.Pos| to cursor position (see |api-indexing|).
----@param pos vim.Pos
 ---@return integer, integer
-function Pos.to_cursor(pos)
-  return pos.row + 1, pos.col
+function Pos:to_cursor()
+  return self.row + 1, self.col
 end
 
 --- Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 ---@param buf integer
 ---@param pos [integer, integer]
-function Pos.cursor(buf, pos)
+---@return vim.Pos
+function M.cursor(buf, pos)
   return Pos.new(buf, pos[1] - 1, pos[2])
 end
 
 --- Converts |vim.Pos| to extmark position (see |api-indexing|).
----@param pos vim.Pos
 ---@return integer, integer
-function Pos.to_extmark(pos)
-  local line_count = api.nvim_buf_line_count(pos.buf)
+function Pos:to_extmark()
+  local line_num = #api.nvim_buf_get_lines(self.buf, 0, -1, true)
 
-  local row = pos.row
-  local col = pos.col
-  if pos.col == 0 and pos.row == line_count then
+  local row = self.row
+  local col = self.col
+  if self.col == 0 and self.row == line_num then
     row = row - 1
-    col = #get_line(pos.buf, row)
+    col = #get_line(self.buf, row)
   end
 
   return row, col
@@ -212,16 +210,16 @@ end
 ---@param buf integer
 ---@param row integer
 ---@param col integer
-function Pos.extmark(buf, row, col)
+---@return vim.Pos
+function M.extmark(buf, row, col)
   return Pos.new(buf, row, col)
 end
 
--- Overload `Range.new` to allow calling this module as a function.
-setmetatable(Pos, {
+setmetatable(M, {
   __call = function(_, ...)
     return Pos.new(...)
   end,
 })
----@cast Pos +fun(buf: integer, row: integer, col: integer): vim.Pos
+---@cast M +fun(buf: integer, row: integer, col: integer): vim.Pos
 
-return Pos
+return M
diff --git a/runtime/lua/vim/range.lua b/runtime/lua/vim/range.lua
index 8ffe880690e..27de39427b6 100644
--- a/runtime/lua/vim/range.lua
+++ b/runtime/lua/vim/range.lua
@@ -6,6 +6,8 @@
 --- Provides operations to compare, calculate, and convert ranges represented by |vim.Range|
 --- objects.
 
+local M = {}
+
 local validate = vim.validate
 local api = vim.api
 
@@ -49,7 +51,6 @@ local api = vim.api
 ---@field private [5] integer underlying representation of buf
 local Range = {}
 
----@private
 ---@param pos vim.Range
 ---@param key any
 function Range.__index(pos, key)
@@ -152,7 +153,6 @@ local function to_inclusive_pos(buf, row, col)
   return row, col
 end
 
----@private
 ---@param r1 vim.Range
 ---@param r2 vim.Range
 function Range.__lt(r1, r2)
@@ -161,7 +161,6 @@ function Range.__lt(r1, r2)
   return cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) == -1
 end
 
----@private
 ---@param r1 vim.Range
 ---@param r2 vim.Range
 function Range.__le(r1, r2)
@@ -170,7 +169,6 @@ function Range.__le(r1, r2)
   return cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) ~= 1
 end
 
----@private
 ---@param r1 vim.Range
 ---@param r2 vim.Range
 function Range.__eq(r1, r2)
@@ -188,29 +186,28 @@ function Range:is_empty()
   return cmp_pos(self.start_row, self.start_col, inclusive_end_row, inclusive_end_col) ~= -1
 end
 
---- Checks whether {outer} range contains {inner} range or position.
+--- Checks whether range contains {inner} range or position.
 ---
----@param outer vim.Range
 ---@param inner vim.Range|vim.Pos
----@return boolean `true` if {outer} range fully contains {inner} range or position.
-function Range.has(outer, inner)
-  if getmetatable(inner) == vim.pos then
+---@return boolean `true` if range fully contains {inner} range or position.
+function Range:has(inner)
+  if getmetatable(inner) == vim.pos._Pos then
     ---@cast inner -vim.Range
-    return cmp_pos(outer.start_row, outer.start_col, inner.row, inner.col) ~= 1
-      and cmp_pos(outer.end_row, outer.end_col, inner.row, inner.col) ~= -1
+    return cmp_pos(self.start_row, self.start_col, inner.row, inner.col) ~= 1
+      and cmp_pos(self.end_row, self.end_col, inner.row, inner.col) ~= -1
   end
   ---@cast inner -vim.Pos
 
   local outer_inclusive_end_row, outer_inclusive_end_col =
-    to_inclusive_pos(outer.buf, outer.end_row, outer.end_col)
+    to_inclusive_pos(self.buf, self.end_row, self.end_col)
   local inner_inclusive_end_row, inner_inclusive_end_col =
     to_inclusive_pos(inner.buf, inner.end_row, inner.end_col)
 
-  return cmp_pos(outer.start_row, outer.start_col, inner.start_row, inner.start_col) ~= 1
-    and cmp_pos(outer.end_row, outer.end_col, inner.end_row, inner.end_col) ~= -1
+  return cmp_pos(self.start_row, self.start_col, inner.start_row, inner.start_col) ~= 1
+    and cmp_pos(self.end_row, self.end_col, inner.end_row, inner.end_col) ~= -1
     -- accounts for empty ranges at the start/end of `outer` that per Neovim API and LSP logic
     -- insert the text outside `outer`
-    and cmp_pos(outer.start_row, outer.start_col, inner_inclusive_end_row, inner_inclusive_end_col) == -1
+    and cmp_pos(self.start_row, self.start_col, inner_inclusive_end_row, inner_inclusive_end_col) == -1
     and cmp_pos(
         outer_inclusive_end_row,
         outer_inclusive_end_col,
@@ -220,27 +217,26 @@ function Range.has(outer, inner)
       == 1
 end
 
---- Computes the common range shared by the given ranges.
+--- Computes the common range shared by range and {r2}
 ---
----@param r1 vim.Range First range to intersect.
 ---@param r2 vim.Range Second range to intersect
----@return vim.Range? range that is present inside both `r1` and `r2`.
+---@return vim.Range? range that is present inside both range and `r2`.
 ---                   `nil` if such range does not exist.
-function Range.intersect(r1, r2)
+function Range:intersect(r2)
   local r1_inclusive_end_row, r1_inclusive_end_col =
-    to_inclusive_pos(r1.buf, r1.end_row, r1.end_col)
+    to_inclusive_pos(self.buf, self.end_row, self.end_col)
   local r2_inclusive_end_row, r2_inclusive_end_col =
     to_inclusive_pos(r2.buf, r2.end_row, r2.end_col)
 
   if
     cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) ~= 1
-    or cmp_pos(r1.start_row, r1.start_col, r2_inclusive_end_row, r2_inclusive_end_col) ~= -1
+    or cmp_pos(self.start_row, self.start_col, r2_inclusive_end_row, r2_inclusive_end_col) ~= -1
   then
     return nil
   end
 
-  local rs = cmp_pos(r1.start_row, r1.start_col, r2.start_row, r2.start_col) ~= 1 and r2 or r1
-  local re = cmp_pos(r1.end_row, r1.end_col, r2.end_row, r2.end_col) ~= -1 and r2 or r1
+  local rs = cmp_pos(self.start_row, self.start_col, r2.start_row, r2.start_col) ~= 1 and r2 or self
+  local re = cmp_pos(self.end_row, self.end_col, r2.end_row, r2.end_col) ~= -1 and r2 or self
   return Range.new(rs.start_row, rs.start_col, re.end_row, re.end_col)
 end
 
@@ -254,17 +250,15 @@ end
 --- -- Convert to LSP range, you can call it in a method style.
 --- local lsp_range = range:to_lsp('utf-16')
 --- ```
----@param range vim.Range
 ---@param position_encoding lsp.PositionEncodingKind
 ---@return lsp.Range
-function Range.to_lsp(range, position_encoding)
-  validate('range', range, 'table')
+function Range:to_lsp(position_encoding)
   validate('position_encoding', position_encoding, 'string', true)
 
   ---@type lsp.Range
   return {
-    ['start'] = vim.pos(range.buf, range.start_row, range.start_col):to_lsp(position_encoding),
-    ['end'] = vim.pos(range.buf, range.end_row, range.end_col):to_lsp(position_encoding),
+    ['start'] = vim.pos(self.buf, self.start_row, self.start_col):to_lsp(position_encoding),
+    ['end'] = vim.pos(self.buf, self.end_row, self.end_col):to_lsp(position_encoding),
   }
 end
 
@@ -283,7 +277,8 @@ end
 ---@param buf integer
 ---@param range lsp.Range
 ---@param position_encoding lsp.PositionEncodingKind
-function Range.lsp(buf, range, position_encoding)
+---@return vim.Range
+function M.lsp(buf, range, position_encoding)
   validate('buf', buf, 'number')
   validate('range', range, 'table')
   validate('position_encoding', position_encoding, 'string')
@@ -306,12 +301,9 @@ end
 --- -- Convert to extmark range, you can call it in a method style.
 --- local extmark_range = range:to_extmark()
 --- ```
----@param range vim.Range
-function Range.to_extmark(range)
-  validate('range', range, 'table')
-
-  local srow, scol = vim.pos(range.buf, range.start_row, range.start_col):to_extmark()
-  local erow, ecol = vim.pos(range.buf, range.end_row, range.end_col):to_extmark()
+function Range:to_extmark()
+  local srow, scol = vim.pos(self.buf, self.start_row, self.start_col):to_extmark()
+  local erow, ecol = vim.pos(self.buf, self.end_row, self.end_col):to_extmark()
   return srow, scol, erow, ecol
 end
 
@@ -328,7 +320,8 @@ end
 ---@param start_col integer
 ---@param end_row integer
 ---@param end_col integer
-function Range.extmark(buf, start_row, start_col, end_row, end_col)
+---@return vim.Range
+function M.extmark(buf, start_row, start_col, end_row, end_col)
   validate('buf', buf, 'number')
   validate('start_row', start_row, 'number')
   validate('start_col', start_col, 'number')
@@ -351,12 +344,9 @@ end
 --- -- Convert to cursor range, you can call it in a method style.
 --- local cursor_range = range:to_cursor()
 --- ```
----@param range vim.Range
-function Range.to_cursor(range)
-  validate('range', range, 'table')
-
-  local srow, scol = vim.pos(range.buf, range.start_row, range.start_col):to_cursor()
-  local erow, ecol = vim.pos(range.buf, range.end_row, range.end_col):to_cursor()
+function Range:to_cursor()
+  local srow, scol = vim.pos(self.buf, self.start_row, self.start_col):to_cursor()
+  local erow, ecol = vim.pos(self.buf, self.end_row, self.end_col):to_cursor()
   return srow, scol, erow, ecol
 end
 
@@ -374,7 +364,8 @@ end
 ---@param buf integer
 ---@param start_pos [integer, integer]
 ---@param end_pos [integer, integer]
-function Range.cursor(buf, start_pos, end_pos)
+---@return vim.Range
+function M.cursor(buf, start_pos, end_pos)
   validate('buf', buf, 'number')
   validate('range', start_pos, 'table')
   validate('range', end_pos, 'table')
@@ -385,13 +376,12 @@ function Range.cursor(buf, start_pos, end_pos)
   return Range.new(start, end_)
 end
 
--- Overload `Range.new` to allow calling this module as a function.
-setmetatable(Range, {
+setmetatable(M, {
   __call = function(_, ...)
     return Range.new(...)
   end,
 })
----@cast Range +fun(start: vim.Pos, end_: vim.Pos): vim.Range
----@cast Range +fun(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): vim.Range
+---@cast M +fun(start: vim.Pos, end_: vim.Pos): vim.Range
+---@cast M +fun(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): vim.Range
 
-return Range
+return M