From 5b40a1c09dda83275784053b325ad16626fc55f2 Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Tue, 5 Dec 2023 18:35:22 -0800
Subject: feat(lua): implement Iter:join() (#26416)

---
 runtime/lua/vim/iter.lua | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 874bdfb437..e9c2b66bf2 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -356,6 +356,18 @@ function ListIter.totable(self)
   return self._table
 end
 
+--- Collect the iterator into a delimited string.
+---
+--- Each element in the iterator is joined into a string separated by {delim}.
+---
+--- Consumes the iterator.
+---
+--- @param delim string Delimiter
+--- @return string
+function Iter.join(self, delim)
+  return table.concat(self:totable(), delim)
+end
+
 --- Folds ("reduces") an iterator into a single value.
 ---
 --- Examples:
-- 
cgit 


From 69ffbb76c237fcbba24de80f1b5346d92642e800 Mon Sep 17 00:00:00 2001
From: Will Hopkins <willothyh@gmail.com>
Date: Tue, 12 Dec 2023 12:27:24 -0800
Subject: feat(iter): add `Iter.take` (#26525)

---
 runtime/lua/vim/iter.lua | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index e9c2b66bf2..8e602c406a 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -592,6 +592,41 @@ function ListIter.rfind(self, f) -- luacheck: no unused args
   self._head = self._tail
 end
 
+--- Transforms an iterator to yield only the first n values.
+---
+--- Example:
+---
+--- ```lua
+--- local it = vim.iter({ 1, 2, 3, 4 }):take(2)
+--- it:next()
+--- -- 1
+--- it:next()
+--- -- 2
+--- it:next()
+--- -- nil
+--- ```
+---
+---@param n integer
+---@return Iter
+function Iter.take(self, n)
+  local next = self.next
+  local i = 0
+  self.next = function()
+    if i < n then
+      i = i + 1
+      return next(self)
+    end
+  end
+  return self
+end
+
+---@private
+function ListIter.take(self, n)
+  local inc = self._head < self._tail and 1 or -1
+  self._tail = math.min(self._tail, self._head + n * inc)
+  return self
+end
+
 --- "Pops" a value from a |list-iterator| (gets the last value and decrements the tail).
 ---
 --- Example:
-- 
cgit 


From d51b6157473c4830313b566116aa3ad38dc97412 Mon Sep 17 00:00:00 2001
From: dundargoc <gocdundar@gmail.com>
Date: Wed, 13 Dec 2023 14:04:24 +0100
Subject: refactor: fix luals warnings

---
 runtime/lua/vim/iter.lua | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 8e602c406a..b658dde099 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -432,6 +432,7 @@ end
 --- ```
 ---
 ---@return any
+---@diagnostic disable-next-line: unused-local
 function Iter.next(self) -- luacheck: no unused args
   -- This function is provided by the source iterator in Iter.new. This definition exists only for
   -- the docstring
@@ -489,6 +490,7 @@ end
 --- ```
 ---
 ---@return any
+---@diagnostic disable-next-line: unused-local
 function Iter.peek(self) -- luacheck: no unused args
   error('peek() requires a list-like table')
 end
@@ -568,12 +570,13 @@ end
 ---@see Iter.find
 ---
 ---@return any
+---@diagnostic disable-next-line: unused-local
 function Iter.rfind(self, f) -- luacheck: no unused args
   error('rfind() requires a list-like table')
 end
 
 ---@private
-function ListIter.rfind(self, f) -- luacheck: no unused args
+function ListIter.rfind(self, f)
   if type(f) ~= 'function' then
     local val = f
     f = function(v)
@@ -640,6 +643,7 @@ end
 --- ```
 ---
 ---@return any
+---@diagnostic disable-next-line: unused-local
 function Iter.nextback(self) -- luacheck: no unused args
   error('nextback() requires a list-like table')
 end
@@ -669,6 +673,7 @@ end
 --- ```
 ---
 ---@return any
+---@diagnostic disable-next-line: unused-local
 function Iter.peekback(self) -- luacheck: no unused args
   error('peekback() requires a list-like table')
 end
@@ -725,6 +730,7 @@ end
 ---
 ---@param n number Number of values to skip.
 ---@return Iter
+---@diagnostic disable-next-line: unused-local
 function Iter.skipback(self, n) -- luacheck: no unused args
   error('skipback() requires a list-like table')
   return self
@@ -791,6 +797,7 @@ end
 ---@param first number
 ---@param last number
 ---@return Iter
+---@diagnostic disable-next-line: unused-local
 function Iter.slice(self, first, last) -- luacheck: no unused args
   error('slice() requires a list-like table')
   return self
-- 
cgit 


From a767c046f4e6bff1412269d56a8edfe33857d954 Mon Sep 17 00:00:00 2001
From: JD <46619169+rudiejd@users.noreply.github.com>
Date: Wed, 10 Jan 2024 21:57:51 -0500
Subject: feat(vim.iter): add Iter:flatten  (#26786)

Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Jongwook Choi <wookayin@gmail.com>
---
 runtime/lua/vim/iter.lua | 82 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 78 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index b658dde099..c6feeea3dc 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -112,6 +112,35 @@ local function sanitize(t)
   return t
 end
 
+--- Flattens a single list-like table. Errors if it attempts to flatten a
+--- dict-like table
+---@param v table table which should be flattened
+---@param max_depth number depth to which the table should be flattened
+---@param depth number current iteration depth
+---@param result table output table that contains flattened result
+---@return table|nil flattened table if it can be flattened, otherwise nil
+local function flatten(v, max_depth, depth, result)
+  if depth < max_depth and type(v) == 'table' then
+    local i = 0
+    for _ in pairs(v) do
+      i = i + 1
+
+      if v[i] == nil then
+        -- short-circuit: this is not a list like table
+        return nil
+      end
+
+      if flatten(v[i], max_depth, depth + 1, result) == nil then
+        return nil
+      end
+    end
+  else
+    result[#result + 1] = v
+  end
+
+  return result
+end
+
 --- Determine if the current iterator stage should continue.
 ---
 --- If any arguments are passed to this function, then return those arguments
@@ -179,6 +208,54 @@ function ListIter.filter(self, f)
   return self
 end
 
+--- Flattens a |list-iterator|, un-nesting nested values up to the given {depth}.
+--- Errors if it attempts to flatten a dict-like value.
+---
+--- Examples:
+---
+--- ```lua
+--- vim.iter({ 1, { 2 }, { { 3 } } }):flatten():totable()
+--- -- { 1, 2, { 3 } }
+---
+--- vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
+--- -- { 1, { a = 2 }, 3 }
+---
+--- vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable()
+--- -- error: attempt to flatten a dict-like table
+--- ```
+---
+---@param depth? number Depth to which |list-iterator| should be flattened
+---                        (defaults to 1)
+---@return Iter
+function Iter.flatten(self, depth) -- luacheck: no unused args
+  error('flatten() requires a list-like table')
+end
+
+---@private
+function ListIter.flatten(self, depth)
+  depth = depth or 1
+  local inc = self._head < self._tail and 1 or -1
+  local target = {}
+
+  for i = self._head, self._tail - inc, inc do
+    local flattened = flatten(self._table[i], depth, 0, {})
+
+    -- exit early if we try to flatten a dict-like table
+    if flattened == nil then
+      error('flatten() requires a list-like table')
+    end
+
+    for _, v in pairs(flattened) do
+      target[#target + 1] = v
+    end
+  end
+
+  self._head = 1
+  self._tail = #target + 1
+  self._table = target
+  return self
+end
+
 --- Maps the items of an iterator pipeline to the values returned by `f`.
 ---
 --- If the map function returns nil, the value is filtered from the iterator.
@@ -461,9 +538,8 @@ end
 --- ```
 ---
 ---@return Iter
-function Iter.rev(self)
+function Iter.rev(self) -- luacheck: no unused args
   error('rev() requires a list-like table')
-  return self
 end
 
 ---@private
@@ -733,7 +809,6 @@ end
 ---@diagnostic disable-next-line: unused-local
 function Iter.skipback(self, n) -- luacheck: no unused args
   error('skipback() requires a list-like table')
-  return self
 end
 
 ---@private
@@ -800,7 +875,6 @@ end
 ---@diagnostic disable-next-line: unused-local
 function Iter.slice(self, first, last) -- luacheck: no unused args
   error('slice() requires a list-like table')
-  return self
 end
 
 ---@private
-- 
cgit 


From 2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 9 Jan 2024 17:36:46 +0000
Subject: fix(doc): improve doc generation of types using lpeg

Added a lpeg grammar for LuaCATS and use it in lua2dox.lua
---
 runtime/lua/vim/iter.lua | 48 ++++++++++++++++++++++++------------------------
 1 file changed, 24 insertions(+), 24 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index c6feeea3dc..a63d5ba565 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -181,9 +181,9 @@ end
 --- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
 --- ```
 ---
----@param f function(...):bool Takes all values returned from the previous stage
----                            in the pipeline and returns false or nil if the
----                            current iterator element should be removed.
+---@param f fun(...):bool Takes all values returned from the previous stage
+---                       in the pipeline and returns false or nil if the
+---                       current iterator element should be removed.
 ---@return Iter
 function Iter.filter(self, f)
   return self:map(function(...)
@@ -272,11 +272,11 @@ end
 --- -- { 6, 12 }
 --- ```
 ---
----@param f function(...):any Mapping function. Takes all values returned from
----                           the previous stage in the pipeline as arguments
----                           and returns one or more new values, which are used
----                           in the next pipeline stage. Nil return values
----                           are filtered from the output.
+---@param f fun(...):any Mapping function. Takes all values returned from
+---                      the previous stage in the pipeline as arguments
+---                      and returns one or more new values, which are used
+---                      in the next pipeline stage. Nil return values
+---                      are filtered from the output.
 ---@return Iter
 function Iter.map(self, f)
   -- Implementation note: the reader may be forgiven for observing that this
@@ -340,9 +340,9 @@ end
 ---
 --- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
 ---
----@param f function(...) Function to execute for each item in the pipeline.
----                       Takes all of the values returned by the previous stage
----                       in the pipeline as arguments.
+---@param f fun(...) Function to execute for each item in the pipeline.
+---                  Takes all of the values returned by the previous stage
+---                  in the pipeline as arguments.
 function Iter.each(self, f)
   local function fn(...)
     if select(1, ...) ~= nil then
@@ -464,7 +464,7 @@ end
 ---@generic A
 ---
 ---@param init A Initial value of the accumulator.
----@param f function(acc:A, ...):A Accumulation function.
+---@param f fun(acc:A, ...):A Accumulation function.
 ---@return A
 function Iter.fold(self, init, f)
   local acc = init
@@ -884,9 +884,9 @@ end
 
 --- Returns true if any of the items in the iterator match the given predicate.
 ---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
----                                stage in the pipeline as arguments and returns true if the
----                                predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---                          stage in the pipeline as arguments and returns true if the
+---                          predicate matches.
 function Iter.any(self, pred)
   local any = false
 
@@ -908,9 +908,9 @@ end
 
 --- Returns true if all items in the iterator match the given predicate.
 ---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
----                                stage in the pipeline as arguments and returns true if the
----                                predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---                          stage in the pipeline as arguments and returns true if the
+---                          predicate matches.
 function Iter.all(self, pred)
   local all = true
 
@@ -1106,9 +1106,9 @@ end
 ---
 ---@see |Iter:filter()|
 ---
----@param f function(...):bool Filter function. Accepts the current iterator or table values as
----                            arguments and returns true if those values should be kept in the
----                            final table
+---@param f fun(...):bool Filter function. Accepts the current iterator or table values as
+---                       arguments and returns true if those values should be kept in the
+---                       final table
 ---@param src table|function Table or iterator function to filter
 ---@return table
 function M.filter(f, src, ...)
@@ -1124,9 +1124,9 @@ end
 ---
 ---@see |Iter:map()|
 ---
----@param f function(...):?any Map function. Accepts the current iterator or table values as
----                            arguments and returns one or more new values. Nil values are removed
----                            from the final table.
+---@param f fun(...): any? Map function. Accepts the current iterator or table values as
+---                        arguments and returns one or more new values. Nil values are removed
+---                        from the final table.
 ---@param src table|function Table or iterator function to filter
 ---@return table
 function M.map(f, src, ...)
-- 
cgit 


From ab3a7fc3e3c0166f5792526699f035dd9e057ee9 Mon Sep 17 00:00:00 2001
From: notomo <notomo.motono@gmail.com>
Date: Thu, 18 Jan 2024 22:01:57 +0900
Subject: docs(vim.iter): correct `bool` to `boolean` (#27018)

---
 runtime/lua/vim/iter.lua | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index a63d5ba565..d720745110 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -181,7 +181,7 @@ end
 --- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
 --- ```
 ---
----@param f fun(...):bool Takes all values returned from the previous stage
+---@param f fun(...):boolean Takes all values returned from the previous stage
 ---                       in the pipeline and returns false or nil if the
 ---                       current iterator element should be removed.
 ---@return Iter
@@ -884,7 +884,7 @@ end
 
 --- Returns true if any of the items in the iterator match the given predicate.
 ---
----@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
 function Iter.any(self, pred)
@@ -908,7 +908,7 @@ end
 
 --- Returns true if all items in the iterator match the given predicate.
 ---
----@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
 function Iter.all(self, pred)
@@ -1106,7 +1106,7 @@ end
 ---
 ---@see |Iter:filter()|
 ---
----@param f fun(...):bool Filter function. Accepts the current iterator or table values as
+---@param f fun(...):boolean Filter function. Accepts the current iterator or table values as
 ---                       arguments and returns true if those values should be kept in the
 ---                       final table
 ---@param src table|function Table or iterator function to filter
-- 
cgit 


From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Thu, 15 Feb 2024 17:16:04 +0000
Subject: feat(docs): replace lua2dox.lua

Problem:

The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.

Solution:

Re-implement the flow using Lua, LPEG and treesitter.

- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
  - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
  - LPEG for C parsing (see `scripts/cdoc_parser.lua`)
  - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
  - Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
   - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
---
 runtime/lua/vim/iter.lua | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index d720745110..798428014d 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,4 +1,4 @@
----@defgroup vim.iter
+--- @brief
 ---
 --- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
 --- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
@@ -66,6 +66,7 @@
 
 ---@class IterMod
 ---@operator call:Iter
+
 local M = {}
 
 ---@class Iter
@@ -599,7 +600,7 @@ end
 --- -- 12
 ---
 --- ```
----
+---@param f any
 ---@return any
 function Iter.find(self, f)
   if type(f) ~= 'function' then
@@ -645,6 +646,7 @@ end
 ---
 ---@see Iter.find
 ---
+---@param f any
 ---@return any
 ---@diagnostic disable-next-line: unused-local
 function Iter.rfind(self, f) -- luacheck: no unused args
@@ -724,6 +726,7 @@ function Iter.nextback(self) -- luacheck: no unused args
   error('nextback() requires a list-like table')
 end
 
+--- @nodoc
 function ListIter.nextback(self)
   if self._head ~= self._tail then
     local inc = self._head < self._tail and 1 or -1
@@ -754,6 +757,7 @@ function Iter.peekback(self) -- luacheck: no unused args
   error('peekback() requires a list-like table')
 end
 
+---@nodoc
 function ListIter.peekback(self)
   if self._head ~= self._tail then
     local inc = self._head < self._tail and 1 or -1
-- 
cgit 


From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 27 Feb 2024 15:20:32 +0000
Subject: docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.
---
 runtime/lua/vim/iter.lua | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 798428014d..09de969b5b 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -64,11 +64,13 @@
 --- In addition to the |vim.iter()| function, the |vim.iter| module provides
 --- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.
 
+---@nodoc
 ---@class IterMod
 ---@operator call:Iter
 
 local M = {}
 
+---@nodoc
 ---@class Iter
 local Iter = {}
 Iter.__index = Iter
@@ -77,6 +79,7 @@ Iter.__call = function(self)
 end
 
 --- Special case implementations for iterators on list tables.
+---@nodoc
 ---@class ListIter : Iter
 ---@field _table table Underlying table data
 ---@field _head number Index to the front of a table iterator
-- 
cgit 


From 85b13751a5fc28fadbe74d72982325ca27b4c775 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Wed, 6 Mar 2024 12:15:25 +0000
Subject: refactor(types): more fixes (2)

---
 runtime/lua/vim/iter.lua | 92 ++++++++++++++++++++++++------------------------
 1 file changed, 46 insertions(+), 46 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 09de969b5b..77c8d1d170 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -64,6 +64,9 @@
 --- In addition to the |vim.iter()| function, the |vim.iter| module provides
 --- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.
 
+--- LuaLS is bad at generics which this module mostly deals with
+--- @diagnostic disable:no-unknown
+
 ---@nodoc
 ---@class IterMod
 ---@operator call:Iter
@@ -189,7 +192,7 @@ end
 ---                       in the pipeline and returns false or nil if the
 ---                       current iterator element should be removed.
 ---@return Iter
-function Iter.filter(self, f)
+function Iter:filter(f)
   return self:map(function(...)
     if f(...) then
       return ...
@@ -198,7 +201,7 @@ function Iter.filter(self, f)
 end
 
 ---@private
-function ListIter.filter(self, f)
+function ListIter:filter(f)
   local inc = self._head < self._tail and 1 or -1
   local n = self._head
   for i = self._head, self._tail - inc, inc do
@@ -231,12 +234,13 @@ end
 ---@param depth? number Depth to which |list-iterator| should be flattened
 ---                        (defaults to 1)
 ---@return Iter
-function Iter.flatten(self, depth) -- luacheck: no unused args
+---@diagnostic disable-next-line:unused-local
+function Iter:flatten(depth) -- luacheck: no unused args
   error('flatten() requires a list-like table')
 end
 
 ---@private
-function ListIter.flatten(self, depth)
+function ListIter:flatten(depth)
   depth = depth or 1
   local inc = self._head < self._tail and 1 or -1
   local target = {}
@@ -282,7 +286,7 @@ end
 ---                      in the next pipeline stage. Nil return values
 ---                      are filtered from the output.
 ---@return Iter
-function Iter.map(self, f)
+function Iter:map(f)
   -- Implementation note: the reader may be forgiven for observing that this
   -- function appears excessively convoluted. The problem to solve is that each
   -- stage of the iterator pipeline can return any number of values, and the
@@ -326,7 +330,7 @@ function Iter.map(self, f)
 end
 
 ---@private
-function ListIter.map(self, f)
+function ListIter:map(f)
   local inc = self._head < self._tail and 1 or -1
   local n = self._head
   for i = self._head, self._tail - inc, inc do
@@ -347,7 +351,7 @@ end
 ---@param f fun(...) Function to execute for each item in the pipeline.
 ---                  Takes all of the values returned by the previous stage
 ---                  in the pipeline as arguments.
-function Iter.each(self, f)
+function Iter:each(f)
   local function fn(...)
     if select(1, ...) ~= nil then
       f(...)
@@ -359,7 +363,7 @@ function Iter.each(self, f)
 end
 
 ---@private
-function ListIter.each(self, f)
+function ListIter:each(f)
   local inc = self._head < self._tail and 1 or -1
   for i = self._head, self._tail - inc, inc do
     f(unpack(self._table[i]))
@@ -392,7 +396,7 @@ end
 ---
 ---
 ---@return table
-function Iter.totable(self)
+function Iter:totable()
   local t = {}
 
   while true do
@@ -407,7 +411,7 @@ function Iter.totable(self)
 end
 
 ---@private
-function ListIter.totable(self)
+function ListIter:totable()
   if self.next ~= ListIter.next or self._head >= self._tail then
     return Iter.totable(self)
   end
@@ -445,7 +449,7 @@ end
 ---
 --- @param delim string Delimiter
 --- @return string
-function Iter.join(self, delim)
+function Iter:join(delim)
   return table.concat(self:totable(), delim)
 end
 
@@ -470,7 +474,7 @@ end
 ---@param init A Initial value of the accumulator.
 ---@param f fun(acc:A, ...):A Accumulation function.
 ---@return A
-function Iter.fold(self, init, f)
+function Iter:fold(init, f)
   local acc = init
 
   --- Use a closure to handle var args returned from iterator
@@ -487,7 +491,7 @@ function Iter.fold(self, init, f)
 end
 
 ---@private
-function ListIter.fold(self, init, f)
+function ListIter:fold(init, f)
   local acc = init
   local inc = self._head < self._tail and 1 or -1
   for i = self._head, self._tail - inc, inc do
@@ -513,14 +517,13 @@ end
 --- ```
 ---
 ---@return any
----@diagnostic disable-next-line: unused-local
-function Iter.next(self) -- luacheck: no unused args
+function Iter:next()
   -- This function is provided by the source iterator in Iter.new. This definition exists only for
   -- the docstring
 end
 
 ---@private
-function ListIter.next(self)
+function ListIter:next()
   if self._head ~= self._tail then
     local v = self._table[self._head]
     local inc = self._head < self._tail and 1 or -1
@@ -542,12 +545,12 @@ end
 --- ```
 ---
 ---@return Iter
-function Iter.rev(self) -- luacheck: no unused args
+function Iter:rev()
   error('rev() requires a list-like table')
 end
 
 ---@private
-function ListIter.rev(self)
+function ListIter:rev()
   local inc = self._head < self._tail and 1 or -1
   self._head, self._tail = self._tail - inc, self._head - inc
   return self
@@ -570,13 +573,12 @@ end
 --- ```
 ---
 ---@return any
----@diagnostic disable-next-line: unused-local
-function Iter.peek(self) -- luacheck: no unused args
+function Iter:peek()
   error('peek() requires a list-like table')
 end
 
 ---@private
-function ListIter.peek(self)
+function ListIter:peek()
   if self._head ~= self._tail then
     return self._table[self._head]
   end
@@ -605,7 +607,7 @@ end
 --- ```
 ---@param f any
 ---@return any
-function Iter.find(self, f)
+function Iter:find(f)
   if type(f) ~= 'function' then
     local val = f
     f = function(v)
@@ -652,12 +654,12 @@ end
 ---@param f any
 ---@return any
 ---@diagnostic disable-next-line: unused-local
-function Iter.rfind(self, f) -- luacheck: no unused args
+function Iter:rfind(f) -- luacheck: no unused args
   error('rfind() requires a list-like table')
 end
 
 ---@private
-function ListIter.rfind(self, f)
+function ListIter:rfind(f)
   if type(f) ~= 'function' then
     local val = f
     f = function(v)
@@ -692,7 +694,7 @@ end
 ---
 ---@param n integer
 ---@return Iter
-function Iter.take(self, n)
+function Iter:take(n)
   local next = self.next
   local i = 0
   self.next = function()
@@ -705,7 +707,7 @@ function Iter.take(self, n)
 end
 
 ---@private
-function ListIter.take(self, n)
+function ListIter:take(n)
   local inc = self._head < self._tail and 1 or -1
   self._tail = math.min(self._tail, self._head + n * inc)
   return self
@@ -724,13 +726,12 @@ end
 --- ```
 ---
 ---@return any
----@diagnostic disable-next-line: unused-local
-function Iter.nextback(self) -- luacheck: no unused args
+function Iter:nextback()
   error('nextback() requires a list-like table')
 end
 
 --- @nodoc
-function ListIter.nextback(self)
+function ListIter:nextback()
   if self._head ~= self._tail then
     local inc = self._head < self._tail and 1 or -1
     self._tail = self._tail - inc
@@ -755,13 +756,12 @@ end
 --- ```
 ---
 ---@return any
----@diagnostic disable-next-line: unused-local
-function Iter.peekback(self) -- luacheck: no unused args
+function Iter:peekback()
   error('peekback() requires a list-like table')
 end
 
 ---@nodoc
-function ListIter.peekback(self)
+function ListIter:peekback()
   if self._head ~= self._tail then
     local inc = self._head < self._tail and 1 or -1
     return self._table[self._tail - inc]
@@ -782,7 +782,7 @@ end
 ---
 ---@param n number Number of values to skip.
 ---@return Iter
-function Iter.skip(self, n)
+function Iter:skip(n)
   for _ = 1, n do
     local _ = self:next()
   end
@@ -790,7 +790,7 @@ function Iter.skip(self, n)
 end
 
 ---@private
-function ListIter.skip(self, n)
+function ListIter:skip(n)
   local inc = self._head < self._tail and n or -n
   self._head = self._head + inc
   if (inc > 0 and self._head > self._tail) or (inc < 0 and self._head < self._tail) then
@@ -814,12 +814,12 @@ end
 ---@param n number Number of values to skip.
 ---@return Iter
 ---@diagnostic disable-next-line: unused-local
-function Iter.skipback(self, n) -- luacheck: no unused args
+function Iter:skipback(n) -- luacheck: no unused args
   error('skipback() requires a list-like table')
 end
 
 ---@private
-function ListIter.skipback(self, n)
+function ListIter:skipback(n)
   local inc = self._head < self._tail and n or -n
   self._tail = self._tail - inc
   if (inc > 0 and self._head > self._tail) or (inc < 0 and self._head < self._tail) then
@@ -844,7 +844,7 @@ end
 ---
 ---@param n number The index of the value to return.
 ---@return any
-function Iter.nth(self, n)
+function Iter:nth(n)
   if n > 0 then
     return self:skip(n - 1):next()
   end
@@ -866,7 +866,7 @@ end
 ---
 ---@param n number The index of the value to return.
 ---@return any
-function Iter.nthback(self, n)
+function Iter:nthback(n)
   if n > 0 then
     return self:skipback(n - 1):nextback()
   end
@@ -880,12 +880,12 @@ end
 ---@param last number
 ---@return Iter
 ---@diagnostic disable-next-line: unused-local
-function Iter.slice(self, first, last) -- luacheck: no unused args
+function Iter:slice(first, last) -- luacheck: no unused args
   error('slice() requires a list-like table')
 end
 
 ---@private
-function ListIter.slice(self, first, last)
+function ListIter:slice(first, last)
   return self:skip(math.max(0, first - 1)):skipback(math.max(0, self._tail - last - 1))
 end
 
@@ -894,7 +894,7 @@ end
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
-function Iter.any(self, pred)
+function Iter:any(pred)
   local any = false
 
   --- Use a closure to handle var args returned from iterator
@@ -918,7 +918,7 @@ end
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
-function Iter.all(self, pred)
+function Iter:all(pred)
   local all = true
 
   local function fn(...)
@@ -953,7 +953,7 @@ end
 --- ```
 ---
 ---@return any
-function Iter.last(self)
+function Iter:last()
   local last = self:next()
   local cur = self:next()
   while cur do
@@ -964,7 +964,7 @@ function Iter.last(self)
 end
 
 ---@private
-function ListIter.last(self)
+function ListIter:last()
   local inc = self._head < self._tail and 1 or -1
   local v = self._table[self._tail - inc]
   self._head = self._tail
@@ -1000,7 +1000,7 @@ end
 --- ```
 ---
 ---@return Iter
-function Iter.enumerate(self)
+function Iter:enumerate()
   local i = 0
   return self:map(function(...)
     i = i + 1
@@ -1009,7 +1009,7 @@ function Iter.enumerate(self)
 end
 
 ---@private
-function ListIter.enumerate(self)
+function ListIter:enumerate()
   local inc = self._head < self._tail and 1 or -1
   for i = self._head, self._tail - inc, inc do
     local v = self._table[i]
-- 
cgit 


From 191cca2566a8afe2b2f2744f3eb763d810cc416c Mon Sep 17 00:00:00 2001
From: Will Hopkins <willothyh@gmail.com>
Date: Sat, 2 Mar 2024 14:39:25 -0800
Subject: fix(types): move type annotation for `IterMod`

---
 runtime/lua/vim/iter.lua | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 77c8d1d170..357dd35bdc 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1140,9 +1140,8 @@ function M.map(f, src, ...)
   return Iter.new(src, ...):map(f):totable()
 end
 
----@type IterMod
 return setmetatable(M, {
   __call = function(_, ...)
     return Iter.new(...)
   end,
-})
+}) --[[@as IterMod]]
-- 
cgit 


From ade1b12f49c3b3914c74847d791eb90ea90b56b7 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Fri, 8 Mar 2024 12:25:18 +0000
Subject: docs: support inline markdown

- Tags are now created with `[tag]()`
- References are now created with `[tag]`
- Code spans are no longer wrapped
---
 runtime/lua/vim/iter.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'runtime/lua/vim/iter.lua')

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 357dd35bdc..a37b7f7858 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,7 +1,7 @@
 --- @brief
 ---
---- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
---- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
+--- [vim.iter()]() is an interface for [iterable]s: it wraps a table or function argument into an
+--- [Iter]() object with methods (such as [Iter:filter()] and [Iter:map()]) that transform the
 --- underlying source data. These methods can be chained to create iterator "pipelines": the output
 --- of each pipeline stage is input to the next stage. The first stage depends on the type passed to
 --- `vim.iter()`:
-- 
cgit