More docstrings

docgen.lua

@@ -54,7 +54,7 @@ for f in coroutine.wrap(function() scan('./libs') end) do
 		elseif checkType(s, '@s?m') then
 
 			local method = {parameters = {}}
-			method.name = match(s, '@s?m (%w+)')
+			method.name = match(s, '@s?m ([%w%p]+)')
 			for optional, paramName, paramType in s:gmatch('@(o?)p ([%w%p]+)%s+([%w%p]+)') do
 				insert(method.parameters, {paramName, paramType, optional == 'o'})
 			end
@@ -147,8 +147,25 @@ if not fs.existsSync('docs') then
 	fs.mkdirSync('docs')
 end
 
+local function clean(input, seen)
+
+	local methods = {}
+	for _, method in ipairs(input) do
+		if not seen[method.name] then
+			insert(methods, method)
+		end
+	end
+	return methods
+
+end
+
 for _, class in pairs(docs) do
 
+	local seen = {}
+	for _, v in pairs(class.properties) do seen[v[1]] = true end
+	for _, v in pairs(class.statics) do seen[v.name] = true	end
+	for _, v in pairs(class.methods) do seen[v.name] = true	end
+
 	local f = io.open(pathJoin('docs', class.name .. '.md'), 'w')
 
 	if next(class.parents) then
@@ -168,8 +185,11 @@ for _, class in pairs(docs) do
 
 	for _, parent in ipairs(class.parents) do
 		if docs[parent] and next(docs[parent].properties) then
-			f:write('## Properties Inherited From ', link(parent), '\n\n')
-			writeProperties(f, docs[parent].properties)
+			local properties = docs[parent].properties
+			if next(properties) then
+				f:write('## Properties Inherited From ', link(parent), '\n\n')
+				writeProperties(f, clean(properties, seen))
+			end
 		end
 	end
 
@@ -180,15 +200,21 @@ for _, class in pairs(docs) do
 
 	for _, parent in ipairs(class.parents) do
 		if docs[parent] and next(docs[parent].statics) then
-			f:write('## Static Methods Inherited From ', link(parent), '\n\n')
-			writeMethods(f, docs[parent].statics)
+			local statics = docs[parent].statics
+			if next(statics) then
+				f:write('## Static Methods Inherited From ', link(parent), '\n\n')
+				writeMethods(f, clean(statics, seen))
+			end
 		end
 	end
 
 	for _, parent in ipairs(class.parents) do
 		if docs[parent] and next(docs[parent].methods) then
-			f:write('## Methods Inherited From ', link(parent), '\n\n')
-			writeMethods(f, docs[parent].methods)
+			local methods = docs[parent].methods
+			if next(methods) then
+				f:write('## Methods Inherited From ', link(parent), '\n\n')
+				writeMethods(f, clean(methods, seen))
+			end
 		end
 	end
 

libs/containers/Ban.lua

@@ -13,6 +13,11 @@ function Ban:__init(data, parent)
 	self._user = self.client._users:_insert(data.user)
 end
 
+--[=[
+@m __hash
+@r string
+@d Returns `Ban.user.id`
+]=]
 function Ban:__hash()
 	return self._user._id
 end

libs/containers/Invite.lua

@@ -30,6 +30,11 @@ function Invite:__init(data, parent)
 	end
 end
 
+--[=[
+@m __hash
+@r string
+@d Returns `Invite.code`
+]=]
 function Invite:__hash()
 	return self._code
 end

libs/containers/Reaction.lua

@@ -20,6 +20,11 @@ function Reaction:__init(data, parent)
 	self._emoji_name = data.emoji.name
 end
 
+--[=[
+@m __hash
+@r string
+@d Returns `Reaction.emojiId or Reaction.emojiName`
+]=]
 function Reaction:__hash()
 	return self._emoji_id or self._emoji_name
 end

libs/containers/abstract/Container.lua

@@ -31,10 +31,22 @@ function Container:__init(data, parent)
 	return load(self, data)
 end
 
+--[=[
+@m __eq
+@r boolean
+@d Defines the behavior of the `==` operator. Allows containers to be directly
+compared according to their type and `__hash` return values.
+]=]
 function Container:__eq(other)
 	return self.__class == other.__class and self:__hash() == other:__hash()
 end
 
+--[=[
+@m __tostring
+@r string
+@d Defines the behavior of the `tostring` function. All containers follow the format
+`ClassName: hash`.
+]=]
 function Container:__tostring()
 	return format('%s: %s', self.__name, self:__hash())
 end

libs/containers/abstract/Snowflake.lua

@@ -13,6 +13,11 @@ function Snowflake:__init(data, parent)
 	Container.__init(self, data, parent)
 end
 
+--[=[
+@m __hash
+@r string
+@d Returns `Snowflake.id`
+]=]
 function Snowflake:__hash()
 	return self._id
 end

libs/containers/abstract/UserPresence.lua

@@ -18,6 +18,11 @@ function UserPresence:__init(data, parent)
 	self._user = self.client._users:_insert(data.user)
 end
 
+--[=[
+@m __hash
+@r string
+@d Returns `UserPresence.user.id`
+]=]
 function UserPresence:__hash()
 	return self._user._id
 end

libs/iterables/ArrayIterable.lua

@@ -1,8 +1,8 @@
 --[=[
-@c 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.
-@d description
+@c ArrayIterable x Iterable
+@d 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.
 ]=]
 
 local wrap, yield = coroutine.wrap, coroutine.yield
@@ -29,7 +29,7 @@ function ArrayIterable:__len()
 	end
 end
 
---[=[@p first * Returns the first object in the array]=]
+--[=[@p first * The first object in the array]=]
 function get.first(self)
 	local array = self._array
 	if not array or #array == 0 then
@@ -49,7 +49,7 @@ function get.first(self)
 	end
 end
 
---[=[@p last * Returns the last object in the array]=]
+--[=[@p last * The last object in the array]=]
 function get.last(self)
 	local array = self._array
 	if not array or #array == 0 then
@@ -72,7 +72,7 @@ end
 --[=[
 @m iter
 @r function
-@d Returns an iterator that returns all contained objects in a consistent order.
+@d Returns an iterator for all contained objects in a consistent order.
 ]=]
 function ArrayIterable:iter()
 	local array = self._array

libs/iterables/Cache.lua

@@ -115,7 +115,7 @@ end
 @p k *
 @r *
 @d 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
+calling `__hash` on the contained objects. Unlike Iterable:get, this
 method operates with O(1) complexity.
 ]=]
 function Cache:get(k)

libs/iterables/Iterable.lua

@@ -4,9 +4,8 @@
 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`, `__pairs`, and `get` methods
-can be redefined in sub-classes.
+Note: All sub-classes should implement their own `__init` and `iter` methods and
+all stored objects should have a `__hash` method.
 ]=]
 
 local random = math.random
@@ -15,6 +14,12 @@ local insert, sort, pack = table.insert, table.sort, table.pack
 
 local Iterable = require('class')('Iterable')
 
+--[=[
+@m __pairs
+@r function
+@d Defines the behavior of the `pair` function. Returns an iterator that returns
+a `key, value` pair, where `key` is the result of calling `__hash` on the `value`.
+]=]
 function Iterable:__pairs()
 	return wrap(function()
 		for obj in self:iter() do
@@ -23,6 +28,12 @@ function Iterable:__pairs()
 	end)
 end
 
+--[=[
+@m __len
+@r function
+@d Defines the behavior of the `#` operator. Returns the total number of objects
+stored in the iterable.
+]=]
 function Iterable:__len()
 	local n = 0
 	for _ in self:iter() do
@@ -109,11 +120,15 @@ end
 
 --[=[
 @m count
-@p fn function
+@op fn function
 @r number
-@d Returns the amount of objects that satisfy a predicate.
+@d If a predicate is provided, this returns the number of objects in the iterable
+that satistfy the predicate; otherwise, the total number of objects.
 ]=]
 function Iterable:count(fn)
+	if not fn then
+		return self:__len()
+	end
 	local n = 0
 	for _ in self:findAll(fn) do
 		n = n + 1
@@ -195,11 +210,11 @@ end
 
 --[=[
 @m select
-@p ... *
+@p ... string
 @r table
 @d 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.
+selected from the objects according to the keys provided.
 ]=]
 function Iterable:select(...)
 	local rows = {}

libs/iterables/TableIterable.lua

@@ -1,6 +1,7 @@
 --[=[
 @c TableIterable x Iterable
-@d description
+@d Iterable class that wraps a basic Lua table, where order is not guaranteed.
+Some versions may use a map function to shape the objects before they are accessed.
 ]=]
 
 local wrap, yield = coroutine.wrap, coroutine.yield

libs/utils/Permissions.lua

@@ -24,6 +24,12 @@ function Permissions:__init(value)
 	self._value = tonumber(value) or 0
 end
 
+--[=[
+@m __tostring
+@r string
+@d Defines the behavior of the `tostring` function. Returns a readable list of
+permissions stored for convenience of introspection.
+]=]
 function Permissions:__tostring()
 	if self._value == 0 then
 		return 'Permissions: 0 (none)'
@@ -38,6 +44,12 @@ function Permissions.all()
 	return Permissions(ALL)
 end
 
+--[=[
+@m __eq
+@r boolean
+@d Defines the behavior of the `==` operator. Allows permissions to be directly
+compared according to their value.
+]=]
 function Permissions:__eq(other)
 	return self._value == other._value
 end

libs/utils/Stopwatch.lua

@@ -23,6 +23,12 @@ function Stopwatch:__init(stopped)
 	self._final = stopped and t or nil
 end
 
+--[=[
+@m __tostring
+@r string
+@d Defines the behavior of the `tostring` function. Returns a string that
+represents the elapsed milliseconds for convenience of introspection.
+]=]
 function Stopwatch:__tostring()
 	return format('Stopwatch: %s ms', self.milliseconds)
 end