diff --git a/lua/plenary/init.lua b/lua/plenary/init.lua
index 7b398d73..560c57a2 100644
--- a/lua/plenary/init.lua
+++ b/lua/plenary/init.lua
@@ -8,6 +8,7 @@
 ---@field filetype PlenaryFiletype
 ---@field fun PlenaryFun
 ---@field functional PlenaryFunctional
+---@field iterators PlenaryIterators
 ---@field job PlenaryJob
 ---@field json PlenaryJson
 ---@field log PlenaryLog
diff --git a/lua/plenary/iterators.lua b/lua/plenary/iterators.lua
index 2aac0d20..75e42239 100644
--- a/lua/plenary/iterators.lua
+++ b/lua/plenary/iterators.lua
@@ -13,12 +13,17 @@ local compat = require "plenary.compat"
 -- Tools
 --------------------------------------------------------------------------------
 
+---@class PlenaryIterators
 local exports = {}
 
----@class Iterator
----@field gen function
----@field param any
----@field state any
+---@generic V
+---@alias PlenaryIteratorsIterator fun(table: V[], i?: integer): integer, V?
+
+---@class PlenaryIterator
+---@field gen PlenaryIteratorsIterator
+---@field param table
+---@field state? integer
+---@overload fun(param?: table, state?: integer): integer, any?
 local Iterator = {}
 Iterator.__index = Iterator
 
@@ -35,6 +40,7 @@ function Iterator:__call(param, state)
   return self.gen(param or self.param, state or self.state)
 end
 
+---@return string
 function Iterator:__tostring()
   return "<iterator>"
 end
@@ -87,6 +93,10 @@ local map_gen = function(map, key)
   return key, key, value
 end
 
+---@param param string
+---@param state integer
+---@return integer? state
+---@return string? r
 local string_gen = function(param, state)
   state = state + 1
   if state > #param then
@@ -96,6 +106,18 @@ local string_gen = function(param, state)
   return state, r
 end
 
+---@generic T: table, U: table
+---@alias PlenaryIteratorsRawiterTable fun(obj: T|PlenaryIterator, param?: string, state?: integer): PlenaryIteratorsIterator, T|U|nil, integer?
+
+---@generic T: table, U: table
+---@param obj T|PlenaryIterator
+---@param param? string
+---@param state? integer
+---@return PlenaryIteratorsIterator gen
+---@return T|U|nil param
+---@return integer? state
+---@overload fun(obj: PlenaryIteratorsIterator, param: any, state?: integer): PlenaryIteratorsIterator, any, integer?
+---@overload fun(obj: string): PlenaryIteratorsIterator, string?, integer?
 local rawiter = function(obj, param, state)
   assert(obj ~= nil, "invalid iterator")
 
@@ -133,7 +155,7 @@ end
 ---@param gen any
 ---@param param any
 ---@param state any
----@return Iterator
+---@return PlenaryIterator
 local function wrap(gen, param, state)
   return setmetatable({
     gen = gen,
@@ -143,7 +165,7 @@ local function wrap(gen, param, state)
 end
 
 ---Unwrap an iterator metatable into the iterator triplet
----@param self Iterator
+---@param self PlenaryIterator
 ---@return any
 ---@return any
 ---@return any
@@ -155,7 +177,7 @@ end
 ---@param obj any
 ---@param param any (optional)
 ---@param state any (optional)
----@return Iterator
+---@return PlenaryIterator
 local iter = function(obj, param, state)
   return wrap(rawiter(obj, param, state))
 end
@@ -229,7 +251,7 @@ end
 ---@param start number
 ---@param stop number
 ---@param step number
----@return Iterator
+---@return PlenaryIterator
 local range = function(start, stop, step)
   if step == nil then
     if stop == nil then
@@ -270,7 +292,7 @@ end
 ---Creates an infinite iterator that will yield the arguments
 ---If multiple arguments are passed, the args will be packed and unpacked
 ---@param ...: the arguments to duplicate
----@return Iterator
+---@return PlenaryIterator
 local duplicate = function(...)
   if select("#", ...) <= 1 then
     return wrap(duplicate_gen, select(1, ...), 0)
@@ -283,7 +305,7 @@ exports.duplicate = duplicate
 ---Creates an iterator from a function
 ---NOTE: if the function is a closure and modifies state, the resulting iterator will not be stateless
 ---@param fun function
----@return Iterator
+---@return PlenaryIterator
 local from_fun = function(fun)
   assert(type(fun) == "function")
   return wrap(duplicate_fun_gen, fun, 0)
@@ -292,7 +314,7 @@ exports.from_fun = from_fun
 
 ---Creates an infinite iterator that will yield zeros.
 ---This is an alias to calling duplicate(0)
----@return Iterator
+---@return PlenaryIterator
 local zeros = function()
   return wrap(duplicate_gen, 0, 0)
 end
@@ -300,7 +322,7 @@ exports.zeros = zeros
 
 ---Creates an infinite iterator that will yield ones.
 ---This is an alias to calling duplicate(1)
----@return Iterator
+---@return PlenaryIterator
 local ones = function()
   return wrap(duplicate_gen, 1, 0)
 end
@@ -317,7 +339,7 @@ end
 ---Creates an infinite iterator that will yield random values.
 ---@param n number
 ---@param m number
----@return Iterator
+---@return PlenaryIterator
 local rands = function(n, m)
   if n == nil and m == nil then
     return wrap(rands_nil_gen, 0, 0)
@@ -356,7 +378,7 @@ end
 ---Return an iterator of substrings separated by a string
 ---@param input string: the string to split
 ---@param sep string: the separator to find and split based on
----@return Iterator
+---@return PlenaryIterator
 local split = function(input, sep)
   return wrap(split_gen, { input, sep }, 1)
 end
@@ -387,7 +409,7 @@ end
 
 ---Iterator adapter that maps the previous iterator with a function
 ---@param fun function: The function to map with. Will be called on each element
----@return Iterator
+---@return PlenaryIterator
 function Iterator:map(fun)
   return wrap(map_gen2, { self.gen, self.param, fun }, self.state)
 end
@@ -429,7 +451,7 @@ local flatten_gen = function(_, state)
 end
 
 ---Iterator adapter that will recursivley flatten nested iterator structure
----@return Iterator
+---@return PlenaryIterator
 function Iterator:flatten()
   return wrap(flatten_gen, false, { self.gen, self.param, self.state })
 end
@@ -482,13 +504,13 @@ end
 
 ---Iterator adapter that will filter values
 ---@param fun function: The function to filter values with. If the function returns true, the value will be kept.
----@return Iterator
+---@return PlenaryIterator
 function Iterator:filter(fun)
   return wrap(filter_gen, { self.gen, self.param, fun }, self.state)
 end
 
 ---Iterator adapter that will provide numbers from 1 to n as the first multival
----@return Iterator
+---@return PlenaryIterator
 function Iterator:enumerate()
   local i = 0
   return self:map(function(...)
@@ -618,7 +640,7 @@ end
 ---Used for treating consecutive iterators as a single iterator.
 ---Infinity iterators are supported, but are not recommended.
 ---@param ...: the iterators to chain
----@return Iterator
+---@return PlenaryIterator
 local chain = function(...)
   local n = numargs(...)
 
@@ -667,7 +689,7 @@ end
 ---The returned iterator is truncated in length to the length of the shortest iterator.
 ---For multi-return iterators only the first variable is used.
 ---@param ...: the iterators to zip
----@return Iterator
+---@return PlenaryIterator
 local zip = function(...)
   local n = numargs(...)
   if n == 0 then