Permalink
Browse files

Merge branch 'core'

  • Loading branch information...
2 parents 5bec16c + f42c7da commit c8482050207b64adb2774fcb4f187f7c650b1ec0 @clinuz clinuz committed Mar 27, 2013
Showing with 83 additions and 78 deletions.
  1. +24 −22 source/kernel/Application.js
  2. +52 −50 source/kernel/ArrayController.js
  3. +7 −6 source/kernel/Controller.js
@@ -2,25 +2,25 @@
//*@public
/**
- In order to provide some convenience and debugging tools we track
- the applications running at any given time. Here we collection them
- for reference later. When _enyo.Application_s are destroyed they know
- to remove themselves from this table.
+ Tracks the applications running at any given time. In order to provide
+ some convenience and debugging tools, we collect the running apps here
+ for later reference. When _enyo.Application_ instances are destroyed,
+ they know to remove themselves from this table.
*/
var applications = enyo.applications = {};
//*@protected
/**
- Used internally to maintain registration of applications with
- the framework.
+ Used internally; maintains registration of applications with the
+ framework.
*/
var register = function (app) {
applications[app.id] = app;
};
//*@protected
/**
- Used internally to unregister applications that have been destroyed.
+ Used internally; unregisters applications that have been destroyed.
*/
var unregister = function (app) {
var kind = app.kindName;
@@ -76,13 +76,13 @@
// cleanup
delete kind.global;
delete kind.name;
- // if the definition does not supply a controller kind we add one
+ // if the definition does not supply a controller kind, we add one
if (!("kind" in kind)) kind.kind = "enyo.Controller";
// create a kind constructor for the controller with all of the given
// properties
ctor = enyo.kind(kind);
inst = new ctor({owner: this, app: this});
- // if the controller is not a global controller we create it as part
+ // if the controller is not a global controller, we create it as part
// of our applications controller store
if (false === global) {
controllers[name] = inst;
@@ -97,20 +97,22 @@
if (!this._is_application) return;
// now that any controllers for the application have been
- // initialized we test to see if we're supposed to
+ // initialized, we test to see if we're supposed to
// automatically start
if (true === this.autoStart) this.start();
});
//*@public
/**
- An _enyo.Application_ can be used to coordinate execution of
- a given collection of _enyo_ objects. There can be one or more
- _enyo.Applications_ running (with some limitation such as which is
- rendered into the _document.body_ - no limitation if they are each
- rendered into separate DOM nodes or nested). It also provides the
- ability to namespace and automatically initialize any _controllers_
- of the application.
+ _enyo.Application_ is a kind used to coordinate execution of a given
+ collection of _enyo_ objects. There may be one or more
+ _enyo.Application_ instances running--with certain limitations, such
+ as which one is rendered into the _document.body_. (There is no
+ limitation if the instances are each rendered into separate DOM nodes
+ or nested.)
+
+ This kind also provides the ability to namespace and automatically
+ initialize any controllers of the application.
*/
enyo.kind({
@@ -146,9 +148,9 @@
//*@public
/**
- If the _autoStart_ flag is set to true this will automatically
- be executed when the constructor is called. Otherwise it can
- be executed whenever the application should begin execution.
+ If the _autoStart_ flag is set to true, this method is
+ automatically executed when the constructor is called. Otherwise,
+ it may be executed whenever the application should begin execution.
*/
start: function () {
if (true === this.renderOnStart) {
@@ -185,8 +187,8 @@
//*@protected
/**
- The overloaded \_create_view method to ensure we supply the
- appropriate values to the new view instance.
+ The overloaded \_create_view method ensures that the appropriate
+ values are supplied to the new view instance.
*/
_create_view: function () {
// this is the constructor for the view kind
@@ -1,12 +1,12 @@
//*@public
/**
- The _enyo.ArrayController_ kind is designed to mimic the behavior
- and API of an ECMAScript 5 Array object with additional functionality
- specific to _enyo.Object_s. By default the object will index its values
- so they are accessible via the bracket-accessor operators. On large datasets
- it is advised that the _store_ property is set to _true_ and only the
- _at_ accessor method is used instead. For small to medium datasets it is
- not necessary.
+ _enyo.ArrayController_ is a kind designed to mimic the behavior and API
+ of an ECMAScript 5 Array object, with additional functionality specific
+ to _enyo.Object_. By default, the object will index its values so they
+ are accessible via the bracket-accessor operators. On large datasets,
+ we recommend setting the _store_ property to _true_ and only using the
+ _at_ accessor method. This is not necessary for small-to-medium
+ datasets.
*/
enyo.kind({
@@ -21,16 +21,16 @@ enyo.kind({
//*@public
/**
- Represents the current length of the array. Setting the
- length directly will have undesirable effects.
+ The current length of the array. Setting the length directly
+ will have undesirable effects.
*/
length: 0,
//*@public
/**
Computed property representing the array structure of the
- underlying data. This is an immutable array as changes __will
- not__ modify the array structure of this controller.
+ underlying data. This is an immutable array, as changes will
+ not modify the array structure of this controller.
*/
data: enyo.computed(function (data) {
if (data) return this.reset(data);
@@ -99,8 +99,8 @@ enyo.kind({
var idx = 1;
var len = this.length;
var changeset = {};
- // unfortunately we have to reindex the entire dataset
- // but even for large ones this is a generic reassignment
+ // unfortunately, we have to reindex the entire dataset,
+ // but even for large ones, this is a generic reassignment
// with little overhead
for (; idx < len; ++idx) this[idx-1] = this[idx];
// delete the reference to the previous last element
@@ -124,11 +124,11 @@ enyo.kind({
var pos = arguments.length;
var nix = idx + pos;
var changeset = {};
- // unfortunately, like with unshift, we have some reindexing
+ // unfortunately, as with unshift, we have some reindexing
// to do, but regardless of the number of elements we're
- // unshifting we can do this in a single pass but we start
+ // unshifting, we can do this in a single pass. we start
// from the end so we don't have to copy twice for every
- // element in the dataset
+ // element in the dataset.
for (; nix >= pos; --nix, --idx) this[nix] = this[idx];
// now we start from the beginning since we should have just
// enough space to add these new elements
@@ -219,7 +219,7 @@ enyo.kind({
}
}
- // we HAVE to update the length if it changed to notify observers/bindings
+ // we have to update the length if it changed to notify observers/bindings
// to data that it may have been updated or bindings to data will still
// have the cached dataset
if (len !== this.length) this.notifyObservers("length", len, this.length);
@@ -284,7 +284,7 @@ enyo.kind({
changeset.removed[idx] = value[idx];
this.remove(value[idx], index);
}
- // we need to create the changeset for any indeces below
+ // we need to create the changeset for any indices below
// the lowest index we found
for (idx = start, len = this.length; idx < len; ++idx) {
changeset.changed[idx] = this[idx];
@@ -331,7 +331,7 @@ enyo.kind({
index = index < 0? 0: index >= len? max: index;
// same for the target index
to = to < 0? 0: to >= len? max: to;
- // if they are the same there's nothing to do
+ // if they are the same, there's nothing to do
if (index === to) return;
// capture the value at index so we can set the new
// index to the appropriate value
@@ -344,18 +344,18 @@ enyo.kind({
// be updated
this.silence();
this.stopNotifications(true);
- // if the index is the top we don't want to do extra
- // calculations or indexing on this step so just
+ // if the index is the top, we don't want to do extra
+ // calculations or indexing on this step, so just
// pop the value
if (index === max) this.pop();
- // unforunately we need to splice the value out of the
+ // unfortunately, we need to splice the value out of the
// dataset before reinserting it at the appropriate spot
else this.splice(index, 1);
// we turn events and notifications back on here so that
// they can produce the final changeset appropriately
this.unsilence();
this.startNotifications(true);
- // readd the value at the correct index
+ // re-add the value at the correct index
this.splice(to, 0, val);
},
@@ -373,8 +373,8 @@ enyo.kind({
/**
Detects the presence of value in the array. Accepts an iterator
and an optional context for that iterator to be called under. Will
- break and return if the iterator returns a truthy value otherwise
- it will return false. On truthy value it returns the value.
+ break and return if the iterator returns a truthy value; otherwise,
+ it will return false. On a truthy value, it returns the value.
*/
find: function (fn, context) {
var idx = 0;
@@ -389,31 +389,33 @@ enyo.kind({
//*@public
/**
- Because the controller cannot detect reassignment to its
- indices (e.g. myvar[3] = "touché") you can do your own custom
- assignment and call this method once when you are finished -
- __if the changes need to be acknowledged in order for notifications
- and events to be sent__. Otherwise, there is no need to call the
- method. There are two ways to call it, without any parameters or
- with an array (or hash whose keys will be used as an array) of the
- indices that have changed. When called
- without parameters it will search for changed indices against
- its cached dataset using direct comparison (or if a _comparator_
- method exists on the controller it will use the result from that
- to determine equality). On larger datasets this is less than ideal.
- If possible, keep track of the indices that have changed and pass those
- to this method so it can simply update its cache and notify observers
- and listeners of the changes to those indices.
+ Because the controller cannot detect reassignment to its indices
+ (e.g., myvar[3] = "touché"), you can do your own custom assignment
+ and call this method once when you are finished--if the changes
+ need to be acknowledged in order for notifications and events to
+ be sent. Otherwise, there is no need to call the method.
- It is important to note that, when using native JavaScript objects
+ There are two ways to call this method--without any parameters, or
+ with an array (or a hash whose keys will be used as an array) of
+ the indices that have changed. When called without parameters, it
+ will search for changed indices against its cached dataset using
+ direct comparison (or if a _comparator_ method exists on the
+ controller, it will use the result from that to determine equality).
+ On larger datasets, this is less than ideal; if possible, keep track
+ of the indices that have changed and pass them to this method so it
+ can simply update its cache and notify observers and listeners of
+ the changes to those indices.
+
+ It is important to note that, when using native JavaScript objects,
the reference is shared. If a property on the hash is directly set
- and this method is called it will be impossible for it to detect changes
- since the references in the comparator are the same. If using native
- objects as your data container it is imperative that you provide the
- indices that have changed to this method. The alternative (and advisable
- path) is to use an _enyo.ObjectController_ to proxy the data of the underlying
- hash and use the setter/getter of that controller that will automatically
- trigger the correct updates when a property has changed.
+ and this method is called, it will be impossible to detect changes
+ since the references in the comparator are the same. If your data is
+ contained in native objects, it is imperative that you provide the
+ indices that have changed to this method. The alternative (and
+ recommended) approach is to use an _enyo.ObjectController_ to proxy
+ the data of the underlying hash and use that controller's setter and
+ getter, which will automatically trigger the correct updates when a
+ property has changed.
*/
changed: function (changed) {
var changeset = {};
@@ -457,7 +459,7 @@ enyo.kind({
//*@protected
create: function () {
this.inherited(arguments);
- // if there were values waiting to be initialized they couldn't
+ // if there were values waiting to be initialized, they couldn't
// have been until now
if (this._init_values) {
this.add.call(this, this._init_values);
@@ -468,7 +470,7 @@ enyo.kind({
//*@protected
constructor: function () {
this.inherited(arguments);
- // if there were any properties passed to the constructor we
+ // if there were any properties passed to the constructor, we
// automatically add them to the array
if (arguments.length) {
var init = [];
@@ -1,8 +1,8 @@
//*@public
/**
- The base class for all controllers in enyo. The _enyo.Controller_
- is a delegate/component that is designed to be a proxy of information.
- This is an abstract class.
+ _enyo.Controller_ is the base kind for all controllers in Enyo. An
+ abstract kind, it is a delegate/component that is designed to be a
+ proxy of information.
*/
enyo.kind({
@@ -23,9 +23,10 @@ enyo.kind({
//*@public
/**
- For all _enyo.Controller_s and subkinds the default source of information
- is the _data_ property. In some cases this is a computed property for
- easier overloading. Can be any type of data.
+ The _data_ property is the default source of information for all
+ instances of _enyo.Controller_ and its subkinds. In some cases, this
+ will be a computed property for easier overloading. It may contain
+ any type of data.
*/
data: null,

0 comments on commit c848205

Please sign in to comment.