data/pandoc.List.lua: improve internal documentation

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,39 +50,6 @@ 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)
-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
--- @return first item equal to the needle, or nil if no such item exists.
--- @return index of that element
-function List:find (needle, init)
-  return List.find_if(self, function(x) return x == needle end, init)
-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
--- @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)
-  init = (init == nil and 1) or (init < 0 and #self - init) or init
-  for i = init, #self do
-    if pred(self[i], i) then
-      return self[i], i
-    end
-  end
-  return nil
-end
-
 --- Adds the given list to the end of this list.
 -- @param list list to appended
 function List:extend (list)
@@ -88,17 +58,6 @@ function List:extend (list)
   end
 end
 
---- 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))
-  for i = 1, #self do
-    res[i] = fn(self[i], i)
-  end
-  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.
@@ -112,6 +71,50 @@ function List:filter (pred)
   return res
 end
 
+--- Returns the value and index of the first occurrence of the given item.
+-- @param needle item to search for
+-- @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)
+  return List.find_if(self, function(x) return x == needle end, init)
+end
+
+--- Returns the value and index of the first element for which the predicate
+--- holds true.
+-- @param pred the predicate function
+-- @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)
+  init = (init == nil and 1) or (init < 0 and #self - init) or init
+  for i = init, #self do
+    if pred(self[i], i) then
+      return self[i], i
+    end
+  end
+  return nil
+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.
+-- @param fn function which is applied to all list items.
+function List:map (fn)
+  local res = setmetatable({}, getmetatable(self))
+  for i = 1, #self do
+    res[i] = fn(self[i], i)
+  end
+  return res
+end
+
 -- Set metatable with __call metamethod. This allows the use of `List`
 -- as a constructor function.
 local ListMT = {