Document full project. Lots of small fixes

src/component.lua

@@ -1,43 +1,46 @@
 --- Component
+-- A Component is a pure data container.
+-- A Component is contained by a single entity.
 
 local Component = {}
 Component.__mt = {
    __index = Component,
 }
 
---- Creates a new Component.
--- @param populate A function that populates the Bag with values
--- @return A Component object
+--- Creates a new ComponentClass.
+-- @param populate Function that populates a Component with values
+-- @return 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)
    end
 
-   local baseComponent = setmetatable({
+   local componentClass = setmetatable({
       __populate = populate,
 
-      __isBaseComponent = true,
+      __isComponentClass = true,
    }, Component.__mt)
 
-   baseComponent.__mt = {
-      __index = baseComponent
+   componentClass.__mt = {
+      __index = componentClass
    }
 
-   return baseComponent
+   return componentClass
 end
 
+--- Internal: Populates a Component with values
 function Component:__populate() -- luacheck: ignore
 end
 
---- Creates and initializes a new Component.
--- @param ... The values passed to the populate function
--- @return A new initialized Component
+--- Internal: Creates and populates a new Component.
+-- @param ... Varargs passed to the populate function
+-- @return A new populated Component
 function Component:__initialize(...)
    local component = setmetatable({
-      __baseComponent = self,
+      __componentClass = self,
 
       __isComponent     = true,
-      __isBaseComponent = false,
+      __isComponentClass = false,
    }, self)
 
    self.__populate(component, ...)