From 71e97c12f6159900e57516e02834af540354d726 Mon Sep 17 00:00:00 2001
From: bakpakin <calsrose@gmail.com>
Date: Thu, 7 May 2015 19:45:28 +0800
Subject: [PATCH] Improve System documentation.

---
 README.md |  7 +++--
 tiny.lua  | 88 +++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 70 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index e775464..b2ec409 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ for simulating large and complex systems. For more explanation on Entity
 Component Systems, here is some
 [basic info](http://en.wikipedia.org/wiki/Entity_component_system "Wikipedia").
 
-Tiny-ecs also works well with Objected Oriented programming in lua because
+Tiny-ecs also works well with objected oriented programming in lua because
 Systems and Entities do not use metatables. This means you can subclass your
 Systems and Entities, and use existing lua class frameworks with tiny-ecs, no problem.
 
@@ -29,7 +29,7 @@ Systems in tiny-ecs describe how to update Entities. Systems select certain Enti
 using a Filter, and then only update those select Entities. Some Systems don't
 update Entities, and instead just act as function callbacks every update. Tiny-ecs
 provides functions for creating Systems easily, as well as creating Systems that
-can be used in an Object Orientented fashion.
+can be used in an object orientented fashion.
 
 ### Filters ###
 Filters are used to select Entities. Filters can be any lua function, but
@@ -81,7 +81,8 @@ Tiny-ecs uses [busted](http://olivinelabs.com/busted/) for testing. Install and
 
 ## Documentation ##
 See API [here](http://bakpakin.github.io/tiny-ecs/doc/).
-Documentation can be generated locally with [LDoc](http://stevedonovan.github.io/ldoc/).
+For the most up-to-date documentation, read the source code, or generate the HTML
+locally with [LDoc](http://stevedonovan.github.io/ldoc/).
 
 ## TODO ##
 
diff --git a/tiny.lua b/tiny.lua
index e37a03b..7a4ea8b 100644
--- a/tiny.lua
+++ b/tiny.lua
@@ -176,18 +176,7 @@ end
 
 --- System functions.
 -- A System is a wrapper around function callbacks for manipulating Entities.
--- @section System
-
--- Use an empty table as a key for identifying Systems. Any table that contains
--- this key is considered a System rather than an Entity.
-local systemTableKey = { "SYSTEM_TABLE_KEY" }
-
--- Check if tables are systems.
-local function isSystem(table)
-    return table[systemTableKey]
-end
-
---- Creates a System. Systems are tables that contain at least one method;
+-- Systems are implemented as tables that contain at least one method;
 -- an update function that takes parameters like so:
 --
 --   * `function system:update(dt)`.
@@ -199,16 +188,45 @@ end
 --   * `function system:onRemove(entity)`
 --   * `function system:onModify(dt)`
 --
--- For Filters, it is conveient to use `tiny.requireAll` or `tiny.requireAny`,
--- but one can write their own filters as well. Set the Filter of your System
--- like so:
+-- For Filters, it is convenient to use `tiny.requireAll` or `tiny.requireAny`,
+-- but one can write their own filters as well. Set the Filter of a System like
+-- so:
 --    system.filter = tiny.requireAll("a", "b", "c")
 -- or
 --    function system:filter(entity)
 --        return entity.myRequiredComponentName ~= nil
 --    end
 --
+-- All Systems also have a few important fields that are initialized when the
+-- system is added to the World. A few are important, and few should be less
+-- commonly used.
+--
+--   * The `active` flag is whether or not the System is updated automatically.
+-- Inactive Systems should be updated manually or not at all via
+-- `system:update(dt)`. Defaults to true.
+--   * The 'entities' field is an ordered list of Entities in the System. This
+-- list can be used to quickly iterate through all Entities in a System.
+--   * The `indices` field is a table of Entity keys to their indices in the
+-- `entities` list. Most Systems can ignore this.
+--   * The `modified` flag is an indicator if the System has been modified in
+-- the last update. If so, the `onModify` callback will be called on the System
+-- in the next update, if it has one. This is usually managed by tiny-ecs, so
+-- users should mostly ignore this, too.
+--
+-- @section System
+
+-- Use an empty table as a key for identifying Systems. Any table that contains
+-- this key is considered a System rather than an Entity.
+local systemTableKey = { "SYSTEM_TABLE_KEY" }
+
+-- Check if tables are systems.
+local function isSystem(table)
+    return table[systemTableKey]
+end
+
+--- Creates a default System.
 -- @param table A table to be used as a System, or `nil` to create a new System.
+-- @return A new System or System class
 function tiny.system(table)
     table = table or {}
     table[systemTableKey] = true
@@ -257,6 +275,7 @@ end
 -- @param table A table to be used as a System, or `nil` to create a new
 -- Processing System.
 -- @see system
+-- @return A new Processing System or Processing System class
 function tiny.processingSystem(table)
     table = table or {}
     table[systemTableKey] = true
@@ -296,6 +315,7 @@ end
 -- Sorted System.
 -- @see system
 -- @see processingSystem
+-- @return A new Sorted System or Sorted System class
 function tiny.sortedSystem(table)
     table = table or {}
     table[systemTableKey] = true
@@ -309,13 +329,13 @@ end
 -- A World is a container that manages Entities and Systems. Typically, a
 -- program uses one World at a time.
 --
--- The tiny-ecs module is set to be the `__index` of all World tables, so the
--- often clearer syntax of `world:method()` can be used for any function in the
--- library. For example, `tiny.add(world, e1, e2, e3)` is the same as
--- `world:add(e1, e2, e3).`
+-- For all World functions except `tiny.world(...)`, object-oriented syntax can
+-- be used instead of the documented syntax. For example,
+-- `tiny.add(world, e1, e2, e3)` is the same as `world:add(e1, e2, e3)`.
 -- @section World
 
-local worldMetaTable = { __index = tiny }
+-- Forward declaration
+local worldMetaTable
 
 --- Creates a new World.
 -- Can optionally add default Systems and Entities.
@@ -646,14 +666,16 @@ function tiny.clearSystems(world)
     end
 end
 
---- Gets count of Entities in World.
+--- Gets number of Entities in the World.
 -- @param world
+-- @return An integer
 function tiny.getEntityCount(world)
     return world.entityCount
 end
 
---- Gets count of Systems in World.
+--- Gets number of Systems in World.
 -- @param world
+-- @return An integer
 function tiny.getSystemCount(world)
     return #(world.systems)
 end
@@ -662,6 +684,7 @@ end
 -- before higher indexed systems.
 -- @param world
 -- @param system
+-- @return An integer between 1 and world:getSystemCount() inclusive
 function tiny.getSystemIndex(world, system)
     return world.systemIndices[system]
 end
@@ -672,6 +695,7 @@ end
 -- @param world
 -- @param system
 -- @param index
+-- @return Old index
 function tiny.setSystemIndex(world, system, index)
     local systemIndices = world.systemIndices
     local oldIndex = systemIndices[system]
@@ -684,6 +708,26 @@ function tiny.setSystemIndex(world, system, index)
     for i = oldIndex, index, index >= oldIndex and 1 or -1 do
         systemIndices[systems[i]] = i
     end
+
+    return oldIndex
 end
 
+-- Construct world metatable.
+worldMetaTable = {
+    __index = {
+        add = tiny.add,
+        addEntity = tiny.addEntity,
+        addSystem = tiny.addSystem,
+        remove = tiny.remove,
+        removeEntity = tiny.removeEntity,
+        update = tiny.update,
+        clearEntities = tiny.clearEntities,
+        clearSystems = tiny.clearSystems,
+        getEntityCount = tiny.getEntityCount,
+        getSystemCount = tiny.getSystemCount,
+        getSystemIndex = tiny.getSystemIndex,
+        setSystemIndex = tiny.setSystemIndex
+    }
+}
+
 return tiny