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/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
-})
+})