make the docs a little nicer

main changes:
- add parameter and return types where applicable
- use @module and @classmod tags at the top of files
- remove some redundant descriptions of return values, especially for functions that return a boolean

recommended next steps:
- more consistent grammar
- add links to classes and functions in descriptions where appropriate
- be consistent about naming Systems vs. SystemClasses and Components vs. ComponentClasses

concord/assemblage.lua

@@ -1,6 +1,5 @@
---- Assemblage
--- An Assemblage is a function that 'makes' an entity something.
--- It does this by :give'ing or :ensure'ing Components, or by :assemble'ing the Entity.
+--- Gives an entity a set of components.
+-- @classmod Assemblage
 
 local Assemblage = {}
 Assemblage.__mt = {
@@ -8,8 +7,8 @@ Assemblage.__mt = {
 }
 
 --- Creates a new Assemblage.
--- @param assemble Function that assembles an Entity
--- @return A new Assemblage
+-- @tparam function assemble Function that assembles an Entity
+-- @treturn Assemblage A new assemblage
 function Assemblage.new(assemble)
    local assemblage = setmetatable({
       __assemble = assemble,
@@ -22,9 +21,9 @@ function Assemblage.new(assemble)
 end
 
 --- Assembles an Entity.
--- @param e Entity to assemble
--- @param ... Varargs to pass to the assemble function
--- @ return self
+-- @tparam Entity e Entity to assemble
+-- @param ... additional arguments to pass to the assemble function
+-- @treturn Assemblage self
 function Assemblage:assemble(e, ...)
    self.__assemble(e, ...)
 
@@ -32,13 +31,13 @@ function Assemblage:assemble(e, ...)
 end
 
 --- Returns true if the Assemblage has a name.
--- @return True if the Assemblage has a name, false otherwise
+-- @treturn boolean
 function Assemblage:hasName()
    return self.__name and true or false
 end
 
 --- Returns the name of the Assemblage.
--- @return Name of the Assemblage
+-- @treturn string
 function Assemblage:getName()
    return self.__name
 end

concord/assemblages.lua

@@ -1,5 +1,5 @@
---- Assemblages
--- Container for registered Assemblages
+--- A container for registered @{Assemblage}s
+-- @module Assemblages
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -8,8 +8,8 @@ local Type = require(PATH..".type")
 local Assemblages = {}
 
 --- Registers an Assemblage.
--- @param name Name to register under
--- @param assemblage Assemblage to register
+-- @string name Name to register under
+-- @tparam Assemblage assemblage Assemblage to register
 function Assemblages.register(name, assemblage)
     if (type(name) ~= "string") then
         error("bad argument #1 to 'Assemblages.register' (string expected, got "..type(name)..")", 3)
@@ -27,16 +27,16 @@ function Assemblages.register(name, assemblage)
     assemblage.__name = name
 end
 
---- Returns true if the containter has the Assemblage with the name
--- @param name Name of the Assemblage to check
--- @return True if the containter has the Assemblage with the name, false otherwise
+--- Returns true if the containter has an Assemblage with the specified name
+-- @string name Name of the Assemblage to check
+-- @treturn boolean
 function Assemblages.has(name)
     return Assemblages[name] and true or false
 end
 
---- Returns the Assemblage with the name
--- @param name Name of the Assemblage to get
--- @return Assemblage with the name
+--- Returns the Assemblage with the specified name
+-- @string name Name of the Assemblage to get
+-- @treturn Assemblage
 function Assemblages.get(name)
     return Assemblages[name]
 end
@@ -46,4 +46,4 @@ return setmetatable(Assemblages, {
     __index = function(_, name)
         error("Attempt to index assemblage '"..tostring(name).."' that does not exist / was not registered", 2)
     end
-})
+})

concord/component.lua

@@ -1,6 +1,5 @@
---- Component
--- A Component is a pure data container.
--- A Component is contained by a single entity.
+--- A pure data container that is contained by a single entity.
+-- @classmod Component
 
 local Component = {}
 Component.__mt = {
@@ -8,8 +7,8 @@ Component.__mt = {
 }
 
 --- Creates a new ComponentClass.
--- @param populate Function that populates a Component with values
--- @return A new ComponentClass
+-- @tparam function populate Function that populates a Component with values
+-- @treturn Component A new ComponentClass
 function Component.new(populate)
    if (type(populate) ~= "function" and type(populate) ~= "nil") then
       error("bad argument #1 to 'Component.new' (function/nil expected, got "..type(populate)..")", 2)
@@ -29,7 +28,7 @@ function Component.new(populate)
    return componentClass
 end
 
---- Internal: Populates a Component with values
+-- Internal: Populates a Component with values
 function Component:__populate() -- luacheck: ignore
 end
 
@@ -39,7 +38,7 @@ end
 function Component:deserialize(data) -- luacheck: ignore
 end
 
---- Internal: Creates a new Component.
+-- Internal: Creates a new Component.
 -- @return A new Component
 function Component:__new()
    local component = setmetatable({
@@ -52,7 +51,7 @@ function Component:__new()
    return component
 end
 
---- Internal: Creates and populates a new Component.
+-- Internal: Creates and populates a new Component.
 -- @param ... Varargs passed to the populate function
 -- @return A new populated Component
 function Component:__initialize(...)
@@ -64,13 +63,13 @@ function Component:__initialize(...)
 end
 
 --- Returns true if the Component has a name.
--- @return True if the Component has a name, false otherwise
+-- @treturn boolean
 function Component:hasName()
    return self.__name and true or false
 end
 
 --- Returns the name of the Component.
--- @return Name of the Component
+-- @treturn string
 function Component:getName()
    return self.__name
 end
@@ -79,4 +78,4 @@ return setmetatable(Component, {
    __call = function(_, ...)
       return Component.new(...)
    end,
-})
+})

concord/components.lua

@@ -1,5 +1,5 @@
---- Components
--- Container for registered ComponentClasss
+--- Container for registered ComponentClasses
+-- @module Components
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -8,8 +8,8 @@ local Type = require(PATH..".type")
 local Components = {}
 
 --- Registers a ComponentClass.
--- @param name Name to register under
--- @param componentClass ComponentClass to register
+-- @string name Name to register under
+-- @tparam Component componentClass ComponentClass to register
 function Components.register(name, componentClass)
     if (type(name) ~= "string") then
         error("bad argument #1 to 'Components.register' (string expected, got "..type(name)..")", 3)
@@ -27,16 +27,16 @@ function Components.register(name, componentClass)
     componentClass.__name = name
 end
 
---- Returns true if the containter has the ComponentClass with the name
--- @param name Name of the ComponentClass to check
--- @return True if the containter has the ComponentClass with the name, false otherwise
+--- Returns true if the containter has the ComponentClass with the specified name
+-- @string name Name of the ComponentClass to check
+-- @treturn boolean
 function Components.has(name)
     return Components[name] and true or false
 end
 
---- Returns the ComponentClass with the name
--- @param name Name of the ComponentClass to get
--- @return ComponentClass with the name
+--- Returns the ComponentClass with the specified name
+-- @string name Name of the ComponentClass to get
+-- @treturn Component
 function Components.get(name)
     return Components[name]
 end
@@ -45,4 +45,4 @@ return setmetatable(Components, {
     __index = function(_, name)
         error("Attempt to index ComponentClass '"..tostring(name).."' that does not exist / was not registered", 2)
     end
-})
+})

concord/entity.lua

@@ -1,7 +1,6 @@
---- Entity
--- Entities are the concrete objects that exist in your project.
--- An Entity have Components and are processed by Systems.
--- An Entity is contained by a maximum of 1 World.
+--- An object that exists in a world. An entity
+-- contains components which are processed by systems.
+-- @classmod Entity
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -14,8 +13,8 @@ Entity.__mt = {
 }
 
 --- Creates a new Entity. Optionally adds it to a World.
--- @param world Optional World to add the entity to
--- @return A new Entity
+-- @tparam[opt] World world World to add the entity to
+-- @treturn Entity A new Entity
 function Entity.new(world)
    if (world ~= nil and not Type.isWorld(world)) then
       error("bad argument #1 to 'Entity.new' (world/nil expected, got "..type(world)..")", 2)
@@ -53,9 +52,9 @@ end
 
 --- Gives an Entity a Component.
 -- If the Component already exists, it's overridden by this new Component
--- @param componentClass ComponentClass to add an instance of
--- @param ... varargs passed to the Component's populate function
--- @return self
+-- @tparam Component componentClass ComponentClass to add an instance of
+-- @param ... additional arguments to pass to the Component's populate function
+-- @treturn Entity self
 function Entity:give(componentClass, ...)
    if not Type.isComponentClass(componentClass) then
       error("bad argument #1 to 'Entity:give' (ComponentClass expected, got "..type(componentClass)..")", 2)
@@ -68,9 +67,9 @@ end
 
 --- Ensures an Entity to have a Component.
 -- If the Component already exists, no action is taken
--- @param componentClass ComponentClass to add an instance of
--- @param ... varargs passed to the Component's populate function
--- @return self
+-- @tparam Component componentClass ComponentClass to add an instance of
+-- @param ... additional arguments to pass to the Component's populate function
+-- @treturn Entity self
 function Entity:ensure(componentClass, ...)
    if not Type.isComponentClass(componentClass) then
       error("bad argument #1 to 'Entity:ensure' (ComponentClass expected, got "..type(componentClass)..")", 2)
@@ -86,8 +85,8 @@ function Entity:ensure(componentClass, ...)
 end
 
 --- Removes a Component from an Entity.
--- @param componentClass ComponentClass of the Component to remove
--- @return self
+-- @tparam Component componentClass ComponentClass of the Component to remove
+-- @treturn Entity self
 function Entity:remove(componentClass)
    if not Type.isComponentClass(componentClass) then
       error("bad argument #1 to 'Entity:remove' (ComponentClass expected, got "..type(componentClass)..")")
@@ -99,8 +98,9 @@ function Entity:remove(componentClass)
 end
 
 --- Assembles an Entity.
--- @param assemblage Assemblage to assemble with
--- @param ... Varargs to pass to the Assemblage's assemble function.
+-- @tparam Assemblage assemblage Assemblage to assemble with
+-- @param ... additional arguments to pass to the Assemblage's assemble function.
+-- @treturn Entity self
 function Entity:assemble(assemblage, ...)
    if not Type.isAssemblage(assemblage) then
       error("bad argument #1 to 'Entity:assemble' (Assemblage expected, got "..type(assemblage)..")")
@@ -112,7 +112,7 @@ function Entity:assemble(assemblage, ...)
 end
 
 --- Destroys the Entity.
--- Removes the Entity from it's World if it's in one.
+-- Removes the Entity from its World if it's in one.
 -- @return self
 function Entity:destroy()
    if self.__world then
@@ -122,7 +122,7 @@ function Entity:destroy()
    return self
 end
 
---- Internal: Tells the World it's in that this Entity is dirty.
+-- Internal: Tells the World it's in that this Entity is dirty.
 -- @return self
 function Entity:__dirty()
    if self.__world then
@@ -133,8 +133,8 @@ function Entity:__dirty()
 end
 
 --- Returns true if the Entity has a Component.
--- @param componentClass ComponentClass of the Component to check
--- @return True if the Entity has the Component, false otherwise
+-- @tparam Component componentClass ComponentClass of the Component to check
+-- @treturn boolean
 function Entity:has(componentClass)
    if not Type.isComponentClass(componentClass) then
       error("bad argument #1 to 'Entity:has' (ComponentClass expected, got "..type(componentClass)..")")
@@ -144,8 +144,8 @@ function Entity:has(componentClass)
 end
 
 --- Gets a Component from the Entity.
--- @param componentClass ComponentClass of the Component to get
--- @return The Component
+-- @tparam Component componentClass ComponentClass of the Component to get
+-- @treturn table
 function Entity:get(componentClass)
    if not Type.isComponentClass(componentClass) then
       error("bad argument #1 to 'Entity:get' (ComponentClass expected, got "..type(componentClass)..")")
@@ -157,19 +157,19 @@ end
 --- Returns a table of all Components the Entity has.
 -- Warning: Do not modify this table.
 -- Use Entity:give/ensure/remove instead
--- @return Table of all Components the Entity has
+-- @treturn table Table of all Components the Entity has
 function Entity:getComponents()
    return self.__components
 end
 
 --- Returns true if the Entity is in a World.
--- @return True if the Entity is in a World, false otherwise
+-- @treturn boolean
 function Entity:inWorld()
    return self.__world and true or false
 end
 
 --- Returns the World the Entity is in.
--- @return The World the Entity is in.
+-- @treturn World
 function Entity:getWorld()
    return self.__world
 end
@@ -213,4 +213,4 @@ return setmetatable(Entity, {
    __call = function(_, ...)
       return Entity.new(...)
    end,
-})
+})

concord/init.lua

@@ -1,4 +1,5 @@
---- init
+---
+-- @module Concord
 
 local PATH = (...):gsub('%.init$', '')
 

concord/list.lua

@@ -1,5 +1,5 @@
---- List
--- Data structure that allows for fast removal at the cost of containing order.
+--- Data structure that allows for fast removal at the cost of containing order.
+-- @classmod List
 
 local List = {}
 List.__mt = {
@@ -7,7 +7,7 @@ List.__mt = {
 }
 
 --- Creates a new List.
--- @return A new List
+-- @treturn List A new List
 function List.new()
    return setmetatable({
       size = 0,
@@ -18,7 +18,7 @@ end
 -- Object must be of reference type
 -- Object may not be the string 'size'
 -- @param obj Object to add
--- @return self
+-- @treturn List self
 function List:__add(obj)
    local size = self.size + 1
 
@@ -31,7 +31,7 @@ end
 
 --- Removes an object from the List.
 -- @param obj Object to remove
--- @return self
+-- @treturn List self
 function List:__remove(obj)
    local index = self[obj]
    if not index then return end
@@ -55,7 +55,7 @@ function List:__remove(obj)
 end
 
 --- Clears the List completely.
--- @return self
+-- @treturn List self
 function List:__clear()
    for i = 1, self.size do
       local o = self[i]
@@ -71,13 +71,13 @@ end
 
 --- Returns true if the List has the object.
 -- @param obj Object to check for
--- @return True if the List has the object, false otherwise
+-- @treturn boolean
 function List:has(obj)
    return self[obj] and true or false
 end
 
 --- Returns the object at an index.
--- @param i Index to get from
+-- @number i Index to get from
 -- @return Object at the index
 function List:get(i)
    return self[i]
@@ -85,7 +85,7 @@ end
 
 --- Returns the index of an object in the List.
 -- @param obj Object to get index of
--- @return index of object in the List.
+-- @treturn number index of object in the List.
 function List:indexOf(obj)
    if (not self[obj]) then
       error("bad argument #1 to 'List:indexOf' (Object was not in List)", 2)

concord/pool.lua

@@ -1,6 +1,6 @@
---- Pool
--- A Pool is used to iterate over Entities with a specific Components
+--- Used to iterate over Entities with a specific Components
 -- A Pool contain a any amount of Entities.
+-- @classmod Pool
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -12,9 +12,9 @@ Pool.__mt = {
 }
 
 --- Creates a new Pool
--- @param name Name for the Pool.
--- @param filter Table containing the required BaseComponents
--- @return The new Pool
+-- @string name Name for the Pool.
+-- @tparam table filter Table containing the required BaseComponents
+-- @treturn Pool The new Pool
 function Pool.new(name, filter)
    local pool = setmetatable(List(), Pool.__mt)
 
@@ -27,8 +27,8 @@ function Pool.new(name, filter)
 end
 
 --- Checks if an Entity is eligible for the Pool.
--- @param e Entity to check
--- @return True if the entity is eligible, false otherwise
+-- @tparam Entity e Entity to check
+-- @treturn boolean
 function Pool:__eligible(e)
    for _, component in ipairs(self.__filter) do
       if not e[component] then
@@ -39,9 +39,9 @@ function Pool:__eligible(e)
    return true
 end
 
---- Internal: Adds an Entity to the Pool.
+-- Internal: Adds an Entity to the Pool.
 -- @param e Entity to add
--- @return self
+-- @treturn Pool self
 function Pool:__add(e)
    List.__add(self, e)
    self:onEntityAdded(e)
@@ -49,9 +49,9 @@ function Pool:__add(e)
    return self
 end
 
---- Internal: Removed an Entity from the Pool.
+-- Internal: Removed an Entity from the Pool.
 -- @param e Entity to remove
--- @return self
+-- @treturn Pool self
 function Pool:__remove(e)
    List.__remove(self, e)
    self:onEntityRemoved(e)
@@ -60,7 +60,7 @@ function Pool:__remove(e)
 end
 
 --- Gets the name of the Pool
--- @return Name of the Pool.
+-- @treturn string
 function Pool:getName()
    return self.__name
 end
@@ -73,12 +73,12 @@ function Pool:getFilter()
 end
 
 --- Callback for when an Entity is added to the Pool.
--- @param e Entity that was added.
+-- @tparam Entity e Entity that was added.
 function Pool:onEntityAdded(e) -- luacheck: ignore
 end
 
 -- Callback for when an Entity is removed from the Pool.
--- @param e Entity that was removed.
+-- @tparam Entity e Entity that was removed.
 function Pool:onEntityRemoved(e)  -- luacheck: ignore
 end
 

concord/system.lua

@@ -1,7 +1,7 @@
---- System
--- A System iterates over Entities. From these Entities its get Components and modify them.
+--- Iterates over Entities. From these Entities its get Components and modify them.
 -- A System contains 1 or more Pools.
 -- A System is contained by 1 World.
+-- @classmod System
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -50,7 +50,7 @@ System.mt = {
 
 --- Creates a new SystemClass.
 -- @param ... Variable amounts of filters
--- @return A new SystemClass
+-- @treturn System A new SystemClass
 function System.new(...)
    local systemClass = setmetatable({
       __filter = {...},
@@ -70,7 +70,7 @@ function System.new(...)
    return systemClass
 end
 
---- Internal: Builds a Pool for the System.
+-- Internal: Builds a Pool for the System.
 -- @param baseFilter The 'raw' Filter
 -- @return A new Pool
 function System.__buildPool(baseFilter)
@@ -88,9 +88,9 @@ function System.__buildPool(baseFilter)
    return Pool(name, filter)
 end
 
---- Internal: Evaluates an Entity for all the System's Pools.
+-- Internal: Evaluates an Entity for all the System's Pools.
 -- @param e The Entity to check
--- @return self
+-- @treturn System self
 function System:__evaluate(e)
    for _, pool in ipairs(self.__pools) do
       local has  = pool:has(e)
@@ -106,9 +106,9 @@ function System:__evaluate(e)
    return self
 end
 
---- Internal: Removes an Entity from the System.
+-- Internal: Removes an Entity from the System.
 -- @param e The Entity to remove
--- @return self
+-- @treturn System self
 function System:__remove(e)
    for _, pool in ipairs(self.__pools) do
       if pool:has(e) then
@@ -119,8 +119,8 @@ function System:__remove(e)
    return self
 end
 
---- Internal: Clears all Entities from the System.
--- @return self
+-- Internal: Clears all Entities from the System.
+-- @treturn System self
 function System:__clear()
    for i = 1, #self.__pools do
       self.__pools[i]:__clear()
@@ -130,7 +130,7 @@ function System:__clear()
 end
 
 --- Enables the System.
--- @return self
+-- @treturn System self
 function System:enable()
    self:setEnabled(true)
 
@@ -138,7 +138,7 @@ function System:enable()
 end
 
 --- Disables the System.
--- @return self
+-- @treturn System self
 function System:disable()
    self:setEnabled(false)
 
@@ -146,7 +146,7 @@ function System:disable()
 end
 
 --- Toggles if the System is enabled.
--- @return self
+-- @treturn System self
 function System:toggleEnabled()
    self:setEnabled(not self.__enabled)
 
@@ -154,8 +154,8 @@ function System:toggleEnabled()
 end
 
 --- Sets if the System is enabled
--- @param enable Enable
--- @return self
+-- @tparam boolean enable
+-- @treturn System self
 function System:setEnabled(enable)
    if (not self.__enabled and enable) then
       self.__enabled = true
@@ -169,39 +169,42 @@ function System:setEnabled(enable)
 end
 
 --- Returns is the System is enabled
--- @return True if the System is enabled, false otherwise
+-- @treturn boolean
 function System:isEnabled()
    return self.__enabled
 end
 
 --- Returns the World the System is in.
--- @return The World the System is in
+-- @treturn World
 function System:getWorld()
    return self.__world
 end
 
 --- Returns true if the System has a name.
--- @return True if the System has a name, false otherwise
+-- @treturn boolean
 function System:hasName()
    return self.__name and true or false
 end
 
 --- Returns the name of the System.
--- @return Name of the System
+-- @treturn string
 function System:getName()
    return self.__name
 end
 
+--- Callbacks
+-- @section Callbacks
+
 --- Callback for system initialization.
--- @param world The World the System was added to
+-- @tparam World world The World the System was added to
 function System:init(world) -- luacheck: ignore
 end
 
--- Callback for when a System is enabled.
+--- Callback for when a System is enabled.
 function System:onEnabled() -- luacheck: ignore
 end
 
--- Callback for when a System is disabled.
+--- Callback for when a System is disabled.
 function System:onDisabled() -- luacheck: ignore
 end
 
@@ -209,4 +212,4 @@ return setmetatable(System, {
    __call = function(_, ...)
       return System.new(...)
    end,
-})
+})

concord/systems.lua

@@ -1,5 +1,5 @@
---- Systems
--- Container for registered SystemClasses
+--- Container for registered SystemClasses
+-- @module Systems
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -8,8 +8,8 @@ local Type = require(PATH..".type")
 local Systems = {}
 
 --- Registers a SystemClass.
--- @param name Name to register under
--- @param systemClass SystemClass to register
+-- @tparam string name Name to register under
+-- @tparam System systemClass SystemClass to register
 function Systems.register(name, systemClass)
     if (type(name) ~= "string") then
         error("bad argument #1 to 'Systems.register' (string expected, got "..type(name)..")", 3)
@@ -28,14 +28,14 @@ function Systems.register(name, systemClass)
 end
 
 --- Returns true if the containter has the SystemClass with the name
--- @param name Name of the SystemClass to check
--- @return True if the containter has the SystemClass with the name, false otherwise
+-- @tparam string name Name of the SystemClass to check
+-- @treturn boolean
 function Systems.has(name)
     return Systems[name] and true or false
 end
 
 --- Returns the SystemClass with the name
--- @param name Name of the SystemClass to get
+-- @tparam string name Name of the SystemClass to get
 -- @return SystemClass with the name
 function Systems.get(name)
     return Systems[name]
@@ -45,4 +45,4 @@ return setmetatable(Systems, {
     __index = function(_, name)
         error("Attempt to index system '"..tostring(name).."' that does not exist / was not registered", 2)
     end
-})
+})

concord/type.lua

@@ -5,49 +5,49 @@ local Type = {}
 
 --- Returns if object is an Entity.
 -- @param t Object to check
--- @return True if object is an Entity, false otherwise
+-- @treturn boolean
 function Type.isEntity(t)
    return type(t) == "table" and t.__isEntity or false
 end
 
 --- Returns if object is a ComponentClass.
 -- @param t Object to check
--- @return True if object is an ComponentClass, false otherwise
+-- @treturn boolean
 function Type.isComponentClass(t)
    return type(t) == "table" and t.__isComponentClass or false
 end
 
 --- Returns if object is a Component.
 -- @param t Object to check
--- @return True if object is an Component, false otherwise
+-- @treturn boolean
 function Type.isComponent(t)
    return type(t) == "table" and t.__isComponent or false
 end
 
 --- Returns if object is a SystemClass.
 -- @param t Object to check
--- @return True if object is an SystemClass, false otherwise
+-- @treturn boolean
 function Type.isSystemClass(t)
    return type(t) == "table" and t.__isSystemClass or false
 end
 
 --- Returns if object is a System.
 -- @param t Object to check
--- @return True if object is an System, false otherwise
+-- @treturn boolean
 function Type.isSystem(t)
    return type(t) == "table" and t.__isSystem or false
 end
 
 --- Returns if object is a World.
 -- @param t Object to check
--- @return True if object is an World, false otherwise
+-- @treturn boolean
 function Type.isWorld(t)
    return type(t) == "table" and t.__isWorld or false
 end
 
 --- Returns if object is an Assemblage.
 -- @param t Object to check
--- @return True if object is an Assemblage, false otherwise
+-- @treturn boolean
 function Type.isAssemblage(t)
    return type(t) == "table" and t.__isAssemblage or false
 end

concord/world.lua

@@ -1,8 +1,8 @@
---- World
--- A World is a collection of Systems and Entities
--- A world emits to let Systems iterate
--- A World contains any amount of Systems
--- A World contains any amount of Entities
+--- A collection of Systems and Entities.
+-- A world emits to let Systems iterate.
+-- A World contains any amount of Systems.
+-- A World contains any amount of Entities.
+-- @classmod World
 
 local PATH = (...):gsub('%.[^%.]+$', '')
 
@@ -19,7 +19,7 @@ World.__mt = {
 }
 
 --- Creates a new World.
--- @return The new World
+-- @treturn World The new World
 function World.new()
    local world = setmetatable({
       __entities = List(),
@@ -48,8 +48,8 @@ function World.new()
 end
 
 --- Adds an Entity to the World.
--- @param e Entity to add
--- @return self
+-- @tparam Entity e Entity to add
+-- @treturn World self
 function World:addEntity(e)
    if not Type.isEntity(e) then
       error("bad argument #1 to 'World:addEntity' (Entity expected, got "..type(e)..")", 2)
@@ -66,8 +66,8 @@ function World:addEntity(e)
 end
 
 --- Removes an Entity from the World.
--- @param e Entity to remove
--- @return self
+-- @tparam Entity e Entity to remove
+-- @treturn World self
 function World:removeEntity(e)
    if not Type.isEntity(e) then
       error("bad argument #1 to 'World:removeEntity' (Entity expected, got "..type(e)..")", 2)
@@ -78,7 +78,7 @@ function World:removeEntity(e)
    return self
 end
 
---- Internal: Marks an Entity as dirty.
+-- Internal: Marks an Entity as dirty.
 -- @param e Entity to mark as dirty
 function World:__dirtyEntity(e)
    if not self.__dirty:has(e) then
@@ -86,9 +86,9 @@ function World:__dirtyEntity(e)
    end
 end
 
---- Internal: Flushes all changes to Entities.
+-- Internal: Flushes all changes to Entities.
 -- This processes all entities. Adding and removing entities, as well as reevaluating dirty entities.
--- @return self
+-- @treturn World self
 function World:__flush()
    -- Early out
    if (self.__added.size == 0 and self.__removed.size == 0 and self.__dirty.size == 0) then
@@ -155,8 +155,8 @@ local blacklistedSystemFunctions = {
 -- Callbacks are registered automatically
 -- Entities added before are added to the System retroactively
 -- @see World:emit
--- @param systemClass SystemClass of System to add
--- @return self
+-- @tparam System systemClass SystemClass of System to add
+-- @treturn World self
 function World:addSystem(systemClass)
    if (not Type.isSystemClass(systemClass)) then
       error("bad argument #1 to 'World:addSystems' (SystemClass expected, got "..type(systemClass)..")", 2)
@@ -202,7 +202,7 @@ end
 -- @see World:addSystem
 -- @see World:emit
 -- @param ... SystemClasses of Systems to add
--- @return self
+-- @treturn World self
 function World:addSystems(...)
    for i = 1, select("#", ...) do
       local systemClass = select(i, ...)
@@ -214,8 +214,8 @@ function World:addSystems(...)
 end
 
 --- Returns if the World has a System.
--- @param systemClass SystemClass of System to check for
--- @return True if World has System, false otherwise
+-- @tparam System systemClass SystemClass of System to check for
+-- @treturn boolean
 function World:hasSystem(systemClass)
    if not Type.isSystemClass(systemClass) then
       error("bad argument #1 to 'World:getSystem' (systemClass expected, got "..type(systemClass)..")", 2)
@@ -225,8 +225,8 @@ function World:hasSystem(systemClass)
 end
 
 --- Gets a System from the World.
--- @param systemClass SystemClass of System to get
--- @return System to get
+-- @tparam System systemClass SystemClass of System to get
+-- @treturn System System to get
 function World:getSystem(systemClass)
    if not Type.isSystemClass(systemClass) then
       error("bad argument #1 to 'World:getSystem' (systemClass expected, got "..type(systemClass)..")", 2)
@@ -237,9 +237,9 @@ end
 
 --- Emits a callback in the World.
 -- Calls all functions with the functionName of added Systems
--- @param functionName Name of functions to call.
+-- @string functionName Name of functions to call.
 -- @param ... Parameters passed to System's functions
--- @return self
+-- @treturn World self
 function World:emit(functionName, ...)
    if not functionName or type(functionName) ~= "string" then
       error("bad argument #1 to 'World:emit' (String expected, got "..type(functionName)..")")
@@ -263,7 +263,7 @@ function World:emit(functionName, ...)
 end
 
 --- Removes all entities from the World
--- @return self
+-- @treturn World self
 function World:clear()
    for i = 1, self.__entities.size do
       self:removeEntity(self.__entities[i])
@@ -318,24 +318,24 @@ function World:deserialize(data, append)
 end
 
 --- Returns true if the World has a name.
--- @return True if the World has a name, false otherwise
+-- @treturn boolean
 function World:hasName()
    return self.__name and true or false
 end
 
 --- Returns the name of the World.
--- @return Name of the World
+-- @treturn string
 function World:getName()
    return self.__name
 end
 
 --- Callback for when an Entity is added to the World.
--- @param e The Entity that was added
+-- @tparam Entity e The Entity that was added
 function World:onEntityAdded(e) -- luacheck: ignore
 end
 
 --- Callback for when an Entity is removed from the World.
--- @param e The Entity that was removed
+-- @tparam Entity e The Entity that was removed
 function World:onEntityRemoved(e) -- luacheck: ignore
 end
 

concord/worlds.lua

@@ -8,7 +8,7 @@ local Type = require(PATH..".type")
 local Worlds = {}
 
 --- Registers a World.
--- @param name Name to register under
+-- @tparam string name Name to register under
 -- @param world World to register
 function Worlds.register(name, world)
     if (type(name) ~= "string") then
@@ -28,14 +28,14 @@ function Worlds.register(name, world)
 end
 
 --- Returns true if the containter has the World with the name
--- @param name Name of the World to check
--- @return True if the containter has the World with the name, false otherwise
+-- @tparam string name Name of the World to check
+-- @treturn boolean
 function Worlds.has(name)
     return Worlds[name] and true or false
 end
 
 --- Returns the World with the name
--- @param name Name of the World to get
+-- @tparam string name Name of the World to get
 -- @return World with the name
 function Worlds.get(name)
     return Worlds[name]
@@ -45,4 +45,4 @@ return setmetatable(Worlds, {
     __index = function(_, name)
         error("Attempt to index world '"..tostring(name).."' that does not exist / was not registered", 2)
     end
-})
+})