data/pandoc.List.lua: improve internal documentation

1 files changed, 32 insertions, 29 deletions

diff --git a/data/pandoc.List.lua b/data/pandoc.List.lua
index 442e9c397..f5b118965 100644
--- a/data/pandoc.List.lua
+++ b/data/pandoc.List.lua
@@ -24,6 +24,9 @@ local List = {
   _VERSION = "1.0.0"
 }
 
+--- Create a new list.
+-- @param[opt] o table that should be altered into a list (default: `{}`)
+-- @return the altered input table
 function List:new (o)
   o = o or {}
   setmetatable(o, self)
@@ -47,17 +50,30 @@ function List:clone ()
   return lst
 end
 
---- Checks if the list has an item equal to the given needle.
--- @param needle item to search for
--- @param init index at which the search is started
--- @return true if a list item is equal to the needle, false otherwise
-function List:includes (needle, init)
-  return not (List.find(self, needle, init) == nil)
+--- Adds the given list to the end of this list.
+-- @param list list to appended
+function List:extend (list)
+  for i = 1, #list do
+    self[#self + 1] = list[i]
+  end
+end
+
+--- Returns a new list containing all items satisfying a given condition.
+-- @param pred condition items must satisfy.
+-- @return a new list containing all items for which `test` was true.
+function List:filter (pred)
+  local res = setmetatable({}, getmetatable(self))
+  for i = 1, #self do
+    if pred(self[i], i) then
+      res[#res + 1] = self[i]
+    end
+  end
+  return res
 end
 
 --- Returns the value and index of the first occurrence of the given item.
 -- @param needle item to search for
--- @param init index at which the search is started
+-- @param[opt] init index at which the search is started (default: 1)
 -- @return first item equal to the needle, or nil if no such item exists.
 -- @return index of that element
 function List:find (needle, init)
@@ -67,7 +83,7 @@ end
 --- Returns the value and index of the first element for which the predicate
 --- holds true.
 -- @param pred the predicate function
--- @param init index at which the search is started
+-- @param[opt] init index at which the search is started (default: 1)
 -- @return first item for which `test` succeeds, or nil if no such item exists.
 -- @return index of that element
 function List:find_if (pred, init)
@@ -80,16 +96,16 @@ function List:find_if (pred, init)
   return nil
 end
 
---- Adds the given list to the end of this list.
--- @param list list to appended
-function List:extend (list)
-  for i = 1, #list do
-    self[#self + 1] = list[i]
-  end
+--- Checks if the list has an item equal to the given needle.
+-- @param needle item to search for
+-- @param[opt] init index at which the search is started; defaults to 1.
+-- @return true if a list item is equal to the needle, false otherwise
+function List:includes (needle, init)
+  return not (List.find(self, needle, init) == nil)
 end
 
---- Returns a copy of the current list by applying the given function to all
--- elements.
+--- Returns a copy of the current list by applying the given function to
+-- all elements.
 -- @param fn function which is applied to all list items.
 function List:map (fn)
   local res = setmetatable({}, getmetatable(self))
@@ -99,19 +115,6 @@ function List:map (fn)
   return res
 end
 
---- Returns a new list containing all items satisfying a given condition.
--- @param pred condition items must satisfy.
--- @return a new list containing all items for which `test` was true.
-function List:filter (pred)
-  local res = setmetatable({}, getmetatable(self))
-  for i = 1, #self do
-    if pred(self[i], i) then
-      res[#res + 1] = self[i]
-    end
-  end
-  return res
-end
-
 -- Set metatable with __call metamethod. This allows the use of `List`
 -- as a constructor function.
 local ListMT = {