Iterable documenation

libs/iterables/ArrayIterable.lua

@@ -4,6 +4,13 @@ local Iterable = require('iterables/Iterable')
 
 local ArrayIterable = require('class')('ArrayIterable', Iterable)
 
+--[[
+@class ArrayIterable x Iterable
+
+Iterable class that contains objects in a constant, ordered fashion, although
+the order may change if the internal array is modified. Some versions may
+use a map function to shape the objects before they are accessed.
+]]
 function ArrayIterable:__init(array, map)
 	self._array = array
 	self._map = map
@@ -22,6 +29,12 @@ function ArrayIterable:__len()
 	end
 end
 
+--[[
+@method iter
+@ret function
+
+Returns an iterator that returns all contained objects in a consistent order.
+]]
 function ArrayIterable:iter()
 	local array = self._array
 	if not array then

libs/iterables/Cache.lua

@@ -2,6 +2,9 @@ local Iterable = require('iterables/Iterable')
 
 local Cache = require('class')('Cache', Iterable)
 
+--[[
+@class Cache x Iterable
+]]
 function Cache:__init(array, constructor, parent)
 	local objects = {}
 	for _, data in ipairs(array) do
@@ -100,10 +103,26 @@ function Cache:_load(array, update)
 	end
 end
 
+--[[
+@method get
+@param k: *
+@ret *
+
+Returns an individual object by key, where the key should match the result of
+calling `__hash` on the contained objects. Unlike the default version, this
+method operates with O(1) complexity.
+]]
 function Cache:get(k)
 	return self._objects[k]
 end
 
+--[[
+@method iter
+@ret function
+
+Returns an iterator that returns all contained object. The order of the objects
+is not guaranteed.
+]]
 function Cache:iter()
 	local objects, k, obj = self._objects
 	return function()

libs/iterables/FilteredIterable.lua

@@ -2,13 +2,26 @@ local Iterable = require('iterables/Iterable')
 
 local FilteredIterable = require('class')('FilteredIterable', Iterable)
 
-function FilteredIterable:__init(base, filter)
+--[[
+@class FilteredIterable x Iterable
+
+Iterable class that wraps another iterable and serves a subset of the objects
+that the original iterable contains.
+]]
+function FilteredIterable:__init(base, predicate)
 	self._base = base
-	self._filter = filter
+	self._predicate = predicate
 end
 
+--[[
+@method iter
+@ret function
+
+Returns an iterator that returns all contained object. The order of the objects
+is not guaranteed.
+]]
 function FilteredIterable:iter()
-	return self._base:findAll(self._filter)
+	return self._base:findAll(self._predicate)
 end
 
 return FilteredIterable

libs/iterables/Iterable.lua

@@ -4,10 +4,16 @@ local insert, sort, pack = table.insert, table.sort, table.pack
 
 local Iterable = require('class')('Iterable')
 
---[[ NOTE:
-- this is more of a mixin, without an initializer
-- init and iter methods must be defined in each sub-class
-- len and get can be redefined in any sub-class
+--[[
+@abc Iterable
+
+Abstract base class that defines the base methods and/or properties for a
+general purpose data structure with features that are better suited for an
+object-oriented environment.
+
+Note: All sub-classes must implement their own `__init` and `iter` methods.
+Additionally, more efficient versions of `__len` and `get` methods can be
+redefined in sub-classes.
 ]]
 
 function Iterable:__len()
@@ -22,6 +28,9 @@ end
 @method get
 @param k: *
 @ret *
+
+Returns an individual object by key, where the key should match the result of
+calling `__hash` on the contained objects. Operates with up to O(n) complexity.
 ]]
 function Iterable:get(k) -- objects must be hashable
 	for obj in self:iter() do
@@ -36,6 +45,8 @@ end
 @method find
 @param fn: function
 @ret *
+
+Returns the first object that satisfies a predicate.
 ]]
 function Iterable:find(fn)
 	for obj in self:iter() do
@@ -50,6 +61,8 @@ end
 @method findAll
 @param fn: function
 @ret function
+
+Returns an iterator that returns all objects that satisfy a predicate.
 ]]
 function Iterable:findAll(fn)
 	return wrap(function()
@@ -64,6 +77,9 @@ end
 --[[
 @method forEach
 @param fn: function
+
+Iterates through all objects and calls a function `fn` that takes the
+objects as an argument.
 ]]
 function Iterable:forEach(fn)
 	for obj in self:iter() do
@@ -74,6 +90,8 @@ end
 --[[
 @method random
 @ret *
+
+Returns a random object that is contained in the iterable.
 ]]
 function Iterable:random()
 	local n = 1
@@ -90,6 +108,8 @@ end
 @method count
 @param fn: function
 @ret number
+
+Returns the amount of objects that satisfy a predicate.
 ]]
 function Iterable:count(fn)
 	local n = 0
@@ -141,8 +161,13 @@ end
 
 --[[
 @method toTable
-@param fn: function
+@param [fn]: function
+@param [sortBy]: string
 @ret table
+
+Returns a table that contains references to all objects. If a predicate is
+provided, then only objects that satisfy it will be included. If a `sortBy`
+string is provided, then the table is sorted by that particular property.
 ]]
 function Iterable:toTable(fn, sortBy)
 	local ret = {}
@@ -163,6 +188,10 @@ end
 @method select
 @param ...: *
 @ret table
+
+Similarly to an SQL query, this returns a sorted Lua table of rows where each
+row corresponds to each object in the iterable, and each value in the row is
+selected from the objects according to the arguments provided.
 ]]
 function Iterable:select(...)
 	local rows = {}

libs/iterables/SecondaryCache.lua

@@ -2,6 +2,13 @@ local Iterable = require('iterables/Iterable')
 
 local SecondaryCache = require('class')('SecondaryCache', Iterable)
 
+--[[
+@class SecondaryCache x Iterable
+
+Iterable class that wraps another cache. Objects added to or removed from a
+secondary cache are also automatically added to or removed from the primary
+cache that it wraps.
+]]
 function SecondaryCache:__init(array, primary)
 	local objects = {}
 	for _, data in ipairs(array) do
@@ -37,10 +44,26 @@ function SecondaryCache:_remove(data)
 	return obj
 end
 
+--[[
+@method get
+@param k: *
+@ret *
+
+Returns an individual object by key, where the key should match the result of
+calling `__hash` on the contained objects. Unlike the default version, this
+method operates with O(1) complexity.
+]]
 function SecondaryCache:get(k)
 	return self._objects[k]
 end
 
+--[[
+@method iter
+@ret function
+
+Returns an iterator that returns all contained object. The order of the objects
+is not guaranteed.
+]]
 function SecondaryCache:iter()
 	local objects, k, obj = self._objects
 	return function()

libs/iterables/WeakCache.lua

@@ -3,6 +3,13 @@ local Iterable = require('iterables/Iterable')
 
 local WeakCache = require('class')('WeakCache', Cache)
 
+--[[
+@class WeakCache x Cache
+
+Extends the functionality of a regular cache by making use of weak references
+to the objects that are cached. If all references to an object are weak, as they
+are here, then the object will be deleted on the next garbage collection cycle.
+]]
 function WeakCache:__init(array, constructor, parent)
 	Cache.__init(self, array, constructor, parent)
 	setmetatable(self._objects, {__mode = 'v'})