Refined docs

README.md

@@ -42,7 +42,7 @@ var Health = CES.Component.extend({
 });
 ```
 
-An entity is simply a container of the components.
+An entity is essentially a container of one or more components.
 
 ```js
 var hero = new CES.Entity();
@@ -51,8 +51,9 @@ hero.addComponent(new Velocity(0, 0));
 hero.addComponent(new Health(100));
 ```
 
-A system will get from the world the entities having one or more components,
-and update the components accordingly.
+The system is responsible for updating the entities.
+In a real game there may be a lot of systems, like `CollisionSystem`,
+`RenderSystem`, `ControlSystem` etc.
 
 ```js
 var PhysicSystem = CES.System.extend({
@@ -72,7 +73,8 @@ var PhysicSystem = CES.System.extend({
 ```
 
 The world is the container of all the entities and systems.
-Calling the `update` method will sequentially update all systems.
+Calling the `update` method will *sequentially* update all the systems,
+in the order they were added.
 
 ```js
 var world = new CES.World();

src/component.js

@@ -1,7 +1,7 @@
 var Class = require('./class');
 
 /**
- * A component is the container of some properties that
+ * The components is the container of some properties that
  * the entity possesses. It may also contain some methods.
  * @class
  */
@@ -11,6 +11,7 @@ var Component = module.exports = Class.extend({
      * should be unique.
      * @public
      * @readonly
+     * @property {String} name
      */
     name: ''
 });

src/entity.js

@@ -2,7 +2,7 @@ var Class  = require('./class'),
     Signal = require('./signal');
 
 /**
- * An entity is a container of components.
+ * The entity is the container of components.
  * @class
  */
 var Entity = module.exports = Class.extend({

src/entitylist.js

@@ -1,7 +1,7 @@
 var Class = require('./class');
 
 /**
- * An entity node is a wrapper around an entity, to be added into
+ * The entity node is a wrapper around an entity, to be added into
  * the entity list.
  * @class
  */
@@ -14,7 +14,7 @@ var EntityNode = Class.extend({
 });
 
 /**
- * An entity list is a doubly-linked-list which allows the
+ * The entity list is a doubly-linked-list which allows the
  * entities to be added and removed efficiently.
  * @class
  */

src/family.js

@@ -2,7 +2,7 @@ var Class = require('./class'),
     EntityList = require('./entitylist');
 
 /**
- * A family is a collection of entities having all the specified components.
+ * The family is a collection of entities having all the specified components.
  * @class
  */
 var Family = module.exports = Class.extend({

src/signal.js

@@ -1,7 +1,7 @@
 var Class = require('./class');
 
 /**
- * A signal can register listeners add invoke the listeners with messages.
+ * The signal can register listeners and invoke the listeners with messages.
  * @class
  */
 var Signal = module.exports = Class.extend({

src/system.js

@@ -1,7 +1,7 @@
 var Class = require('./class');
 
 /**
- * A system is responsible for updating the entities.
+ * The system is responsible for updating the entities.
  * @class
  */
 var System = module.exports = Class.extend({

src/world.js

@@ -3,7 +3,7 @@ var Class = require('./class'),
     EntityList = require('./entitylist');
 
 /**
- * A world is the container of all the entities and systems.
+ * The world is the container of all the entities and systems.
  * @class
  */
 var World = module.exports = Class.extend({