Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

More comment cleanup. Enyo-DCO-1.1-Signed-Off-By: Jim Tang (jim.tang@…

…lge.com)
  • Loading branch information...
commit 6fbde8c90b12c30b2c97dff1b705e04a00207255 1 parent b2f05ea
@jdtang jdtang authored
View
102 source/kernel/ObjectController.js
@@ -1,16 +1,16 @@
//*@public
/**
- The _enyo.ObjectController_ is a sophisticated proxy for
- underlying data. Other objects may observe or bind to its
- properties as if they were that of the underlying data object.
- This abstraction allows for the underlying data to be changed
- or modified without the other objects needing to rebind or
- be aware of the change. It can be subclassed to deal with
- specific data object implementations and special needs. This
- particular controller can handle native data hashes or any
- _enyo.Object_ or sub-kind. While data is being proxied by the
- controller, access to its properties should use the _get_ and
- _set_ method of the controller.
+ _enyo.ObjectController_ is a sophisticated proxy for underlying data.
+ Other objects may observe or bind to its properties as if they belonged
+ to the underlying data object. This abstraction allows the underlying
+ data to be modified without the other objects' needing to rebind or be
+ aware of the change. It can be subclassed to deal with specific data
+ object implementations and special needs.
+
+ This particular controller can handle native data hashes or any
+ instances of _enyo.Object_ or its subkinds. While data is being proxied
+ by the controller, its properties should be accessed using the
+ controller's _get_ and _set_ methods.
*/
enyo.kind({
@@ -41,7 +41,7 @@ enyo.kind({
//*@public
get: function (prop) {
var ret;
- // it we are recursing we go straight to the default
+ // if we are recursing, we go straight to the default
// or if the property is data - data is a reserved word
// in this case otherwise we can't get a reference to the
// object
@@ -61,16 +61,18 @@ enyo.kind({
//*@public
/**
- This method is called by the object-controller's _set_ method
- to allow this portion to be overloaded cleanly in cases where
- there is a non-normative behavior required. Accepts the same
- parameters as the normal _set_ method but is expected to return
- a truthy/falsy value to indicate its success. The default behavior
- is to check to see if the _data_ property exists and if the property
- being set is a top-level property of that object. If not it returns
- false. Notification __is__ handled by this method to allow that
- behavior to be overloaded as well. It is responsible for determining
- the previous value and passing that to the notification method.
+ Accepts the same parameters as the normal _set_ method, but returns
+ a truthy/falsy value to indicate its success. This method is called
+ by the object controller's _set_ method to allow this portion to be
+ overloaded cleanly in cases where non-normative behavior is required.
+
+ The default behavior is to check to see whether the _data_ property
+ exists and whether the property being set is a top-level property of
+ the object. If not, the method returns false.
+
+ Notification is handled by this method, allowing that behavior to be
+ overloaded as well. This method is responsible for determining the
+ previous value and passing it to the notification method.
*/
setDataProperty: function (prop, value) {
var data = this.get("data");
@@ -79,37 +81,39 @@ enyo.kind({
this.stopNotifications();
this.notifyObservers(prop, this.get(prop), value);
}
- // if the object is an enyo object instance its notifications will
+ // if the object is an enyo object instance, its notifications will
// automatically fire
enyo.setPath.call(data, prop, value);
// if it is instead a native object, we have already queued the
- // the notification so this will flush it, otherwise, it will do
+ // the notification, so this will flush it; otherwise, it will do
// nothing
this.startNotifications();
return true;
}
- // under any other circumstances return false
+ // under any other circumstances, return false
return false;
},
//*@public
/**
- This method is called by the object-controller's _get_ method
- to allow this portion to be overloaded cleanly in cases where
- there is a non-normative behavior required. Accepts the same
- parameters as the normal _get_ method but is expected to return
- a truthy/explicit-boolean-false value to indicate its success. The
- default behavior is to check to see if the _data_ property exists
- and if the requested property is a first-level property of the object.
- If it is it will return the value. The default getter of the object-
- controller will only execute if this method returns an explicit false.
+ Accepts the same parameters as the normal _get_ method, but returns
+ a truthy or explicit-boolean-false value to indicate its success.
+ This method is called by the object controller's _get_ method to
+ allow this portion to be overloaded cleanly in cases where
+ non-normative behavior is required.
+
+ The default behavior is to check whether the _data_ property exists
+ and whether the requested property is a first-level property of the
+ object. If it is, the value is returned. The object controller's
+ default getter will only execute if this method explicitly returns
+ false.
*/
getDataProperty: function (prop) {
var data = this.get("data");
if (data && this.isAttribute(prop)) {
return enyo.getPath.call(data, prop);
}
- // under any other circumstance return false explicitly
+ // under any other circumstances, return false explicitly
return false;
},
@@ -117,9 +121,9 @@ enyo.kind({
/**
Takes a string parameter and returns a boolean true|false
depending on whether or not the parameter is an attribute
- of the data object. If no data is present it will always return
- false. If the object has its own _isAttribute_ method it will
- return the the execute method. For more complex implementations
+ of the data object. If no data is present, it will always return
+ false. If the object has its own _isAttribute_ method, it will
+ return the execute method. For more complex implementations,
overload this method.
*/
isAttribute: function (prop) {
@@ -142,7 +146,7 @@ enyo.kind({
// we need to go ahead and double check that the data exists
// and is a valid enyo object instance
if (!data || !(data instanceof enyo.Object)) return;
- // if we had a listener registered on the previous data we
+ // if we had a listener registered on the previous data, we
// need to remove it
if (this._listener) {
data.removeObserver("*", this._listener);
@@ -176,7 +180,7 @@ enyo.kind({
//*@public
initData: function (data) {
- // if no data was passed in we try and grab the property
+ // if no data was passed in, we try to grab the property
// on our own
var data = data || this.get("data");
// we need to go ahead and double check that the data exists
@@ -185,7 +189,7 @@ enyo.kind({
// register ourselves as a global listener on the object
// via the special attribute '*'
this._listener = data.addObserver("*", this.notifyObservers, this);
- // go ahead and setup our last reference for the future
+ // go ahead and set up our last reference for the future
this._last = data;
},
@@ -200,14 +204,14 @@ enyo.kind({
//*@protected
/**
- This method attempts to find the correct target(s) and
- notify them of any/all the possible properties to force
- them to synchronize to the current values.
+ Attempts to find the correct target(s) and notify them of any/all
+ possible properties to force them to be synchronized to their
+ current values.
*/
notifyAll: function () {
- // we will try and trick our bindings into firing by simply
- // triggering all of our registered observers since at this
- // moment it is the only way to be sure we get all bindings
+ // we will try to trick our bindings into firing by simply
+ // triggering all of our registered observers, since at this
+ // moment that is the only way to be sure we get all bindings,
// not just our dispatch targets or owner
var observers = this._observers;
var handlers;
@@ -227,8 +231,8 @@ enyo.kind({
//*@protected
/**
- This method is intended to fire only when the _data_ property is
- arbitrarily set on the object-controller.
+ Fires only when the _data_ property is arbitrarily set on the
+ object controller.
*/
dataDidChange: enyo.observer(function () {
if (this._last) this.releaseData(this._last);
View
124 source/kernel/Router.js
@@ -1,11 +1,10 @@
(function (enyo) {
//*@protected
- // each router registers with this list
+ // Each router registers with this list.
var listeners = [];
//*@protected
- // this method is registered as the handler for occasions when
- // the hash change event is fired
+ // This method is registered as the handler for hashchange events.
var hashDidChange = function (hash) {
var list = listeners;
var len = list.length;
@@ -20,49 +19,55 @@
};
//*@protected
/**
- For the browsers we actively support, they all support this
- method of registering for hashchange events.
+ All of our actively-supported browsers support this method of
+ registering for hashchange events.
*/
enyo.ready(function () {enyo.dispatcher.listen(window, "hashchange", hashDidChange)});
//*@public
/**
- The _enyo.Router_ is a kind of controller with the ability to
- interpret changes in the url as well as set changes to the url
- in a cross-browser compatible way. With defined route handling
- state of the application can be managed more closely with the
- location state of the browser. There can be more than one router
- active at any time. Routers _only interact with the hash portion
+ _enyo.Router_ is a controller with the ability to interpret changes
+ in the url as well as set changes to the url in a manner that is
+ compatible across browsers. With defined route handling, the
+ application state can be managed more closely with respect to the
+ location state of the browser. There may be multiple router instances
+ active at any one time. Routers only interact with the hash portion
of the browser location and will not force a reload of the current
- page_.
+ page.
- Routes can be defined one of several ways and can be added at
- startup and/or later programmatically.
+ Routes may be defined in several ways and may be added at startup or
+ added programmatically at a later time.
- A route is a declarative hash that has the following structure:
+ A route is a declarative hash with the following structure:
- {path: "some/path", handler: "function", context: "context"}
+ {path: "some/path", handler: "function", context: "context"}
- The path is a string that can be static (explicitly matched) or
+ The path is a string that may be static (explicitly matched) or
dynamic (matched based on dynamic placeholders). Dynamic paths
- can name elements that will be matched, e.g. {path: ":user/:id"}
- and the handler would be called with 2 parameters filled with the values
- matched by that structure. It is important to note that dynamic
- routes will apply the first match it finds so care must be used to ensure
- the correct route will always be matched (e.g. /users/:user/:id is
- more exact because of the static 'users' portion of the path).
+ may name elements to be matched, e.g.:
- The handler can be a function reference or a string that will be
- mapped to a function first by checking the existence of the function
- on the router, then on any provided context and then in the global
- scope. If a context is provided, the function will be executed under
- that context regardless of where the function was found.
+ {path: ":user/:id"}
+
+ In this case, the handler would be called with two parameters
+ filled with the values matched by that structure. It is important
+ to note that a dynamic route will apply the first match it finds,
+ so care must be used to ensure that the correct route is matched
+ (e.g., `/users/:user/:id` is more exact because of the static
+ `users` portion of the path).
+
+ The handler may be a function reference or a string that will be
+ mapped to a function. A check for the function's existence is
+ conducted first on the router, then on any provided context, and
+ finally in the global scope. If a context is provided, the
+ function will be executed under that context regardless of where
+ the function was found.
- The context property can be an object, an instance or a string that will
- be mapped to an object if possible.
+ The context property may be an object, an instance or a string that
+ will be mapped to an object if possible.
- NOTE: Because we support IE8 we do not currently support _pushState_.
- NOTE: Dynamic routes currently only support letters and numbers.
+ Note that, currently, only letters and numbers are supported in
+ dynamic routes. Also, because we support IE8, we do not currently
+ support _pushState_.
*/
enyo.kind({
//*@public
@@ -71,17 +76,17 @@
kind: "enyo.Controller",
//*@public
/**
- If the router is listening it will respond to hash changes or
- internal events. If this flag is set to false it will stop
- responding. This can be changed at any time.
+ If true, the router will respond to hash changes or internal events.
+ If this flag is set to false, it will stop responding. This may be
+ changed at any time.
*/
listening: true,
//*@public
/**
- If this is set to true it will not respond to hash changes in
- the browser or be able to trigger them. Instead it could be
- used internally to maintain or trigger state changes in an
- application without changing location.
+ If true, the router will neither respond to hash changes in the
+ browser nor be able to trigger them. Instead, it may be used
+ internally to maintain or trigger state changes in an application
+ without changing location.
*/
internalOnly: false,
//*@protected
@@ -91,17 +96,17 @@
//*@public
/**
The _defaultRoute_ should have the same structure as a normal
- route (hash). It can be arbitrarily assigned to this property
- or mixed in to the routes array with a special _default: true_
- flag set. For any unmatched hash changes this route will be
+ route (hash). It may be arbitrarily assigned to this property
+ or mixed into the routes array with a special _default: true_
+ flag set. For any unmatched hash changes, this route will be
executed and passed the path that was not matched.
*/
defaultRoute: null,
//*@public
/**
- By default a router will attempt to trigger the correct route
- for the current browser location when it is created. Set this
- to false to keep it from performing this startup routine.
+ By default, when a router is created, it will attempt to trigger
+ the correct route for the current browser location. Set this
+ to false to prevent this from happening.
*/
triggerOnStart: true,
//*@protected
@@ -110,19 +115,20 @@
/**
The _routes_ object constitutes the handlers for this router.
Routes are string paths, static or dynamic, that route particular
- hash-change events.
+ hash change events.
*/
routes: null,
//*@public
/**
- Trigger a change without necessarily requiring a change to
- occur. If called without a parameter it will force the
- route that matches the current browser location to fire.
- If a string is passed to this method it will trigger an
- internal only event (will not change the browser location).
- If it is passed a hash, it will try to use a _location_ property
- while looking for optional _change_ and _global_ properties.
- If the _change_ property is present and true it will force a
+ Triggers a change without necessarily requiring a change to occur.
+ If called without a parameter, it will force the route that matches
+ the current browser location to fire. If a string is passed in, this
+ method will trigger an internal-only event (i.e., the browser
+ location will not be changed). If it is passed a hash, the method
+ will try to use a _location_ property while looking for optional
+ _change_ and _global_ properties.
+
+ If the _change_ property is present and true, it will force a
_location.hash_ change in the browser (this is always global).
If the _global_ property is present and true and _change_ is
not present or false, it will trigger an internal event that
@@ -207,7 +213,7 @@
//*@protected
execHandler: function (context, handler, args, route) {
var fn = handler;
- // if the handler is defined as a string we need to determine if
+ // if the handler is defined as a string, we need to determine if
// it is relative to the router, relative to the context, or a named
// function in the global scope
if ("string" === typeof handler) {
@@ -217,16 +223,16 @@
}
} else context = this;
// first check to see if the handler is a named property
- // on the router otherwise try the context itself
+ // on the router; otherwise, try the context itself
fn = this[handler] || context[handler];
if ("function" === typeof fn) {
- // in the case we actually found it, lets not go hunting
+ // in case we actually found it, let's not go hunting
// next time
route.handler = fn;
route.context = context;
}
}
- // if we have an actual handler, lets execute it now
+ // if we have an actual handler, let's execute it now
if (fn && "function" === typeof fn) {
fn.apply(context, args);
return true;
@@ -262,7 +268,7 @@
route = dynamic[idx];
regex = route.regex;
if ((matches = regex.exec(path))) {
- // we need to strip the full match off so we can
+ // we need to strip off the full match so we can
// use the other matches as parameters
matches = matches.slice(1);
handler = route.handler;
View
55 source/kernel/ViewController.js
@@ -2,10 +2,9 @@
//*@public
/**
- The _enyo.ViewController_ kind is an abstract class
- designed for a tightly-coupled controller and view
- where the controller owns the view and maintains its
- state and lifecycle.
+ _enyo.ViewController_ is an abstract kind designed for use in a
+ tightly-coupled controller and view, in which the controller owns
+ the view and maintains its state and lifecycle.
*/
enyo.kind({
@@ -20,20 +19,19 @@
//*@public
/**
- The view property can be a string representing a kind,
- a constructor for a kind or an object literal defining
- the view structure to be instanced. Once the view controller
- has been initialized this property will be a reference
- to the instance of the view owned by this controller.
+ This may be a string representing a kind, a constructor for a kind,
+ or an object literal defining the view structure to be instanced.
+ Once the view controller has been initialized, this property will
+ be a reference to the instance of the view owned by this controller.
*/
view: null,
//*@public
/**
- The render target is a string that represents the target
- DOM element in which to render the controllers view. By default
- this is set to the special identifier: "document.body". It
- can also be set to a unique DOM element __id__ attribute.
+ A string that represents the target DOM element in which to render
+ the controller's view. By default, this is set to the special
+ identifier: `"document.body"`. It may also be set to a unique DOM
+ element __id__ attribute.
*/
renderTarget: "document.body",
@@ -48,23 +46,23 @@
//*@protected
/**
- On object initialization finds or creates the appropriate
+ On object initialization, finds or creates the appropriate
kind for the view of this controller.
*/
_view_kind: enyo.computed(function () {
- // the original definition as supplied by the controllers
+ // the original definition as supplied by the controller's
// own definition
var view = this.view;
// if it is a function, we assume it is a constructor
if ("function" === typeof view) return view;
- // if it is an object literal we assume it is a definition
+ // if it is an object literal, we assume it is a definition
// and note that we create an anonymous kind for the view
- // so it has all of the normal setup of a full-kind
+ // so it has all of the normal setup of a full kind
if ("object" === typeof view) {
if (!view.name) view.name = this._make_view_name();
return enyo.kind(view);
}
- // if it is a string we attempt to find the constructor
+ // if it is a string, we attempt to find the constructor
// it should be pointing to
if ("string" === typeof view) {
view = enyo.getPath(view);
@@ -73,7 +71,7 @@
}
return view;
}
- // if we get here we had nothing and in that case we
+ // if we get here, we had nothing, and in that case we
// can't do anything
throw this.kindName + " cannot initialize without a valid view defined";
}, {cached: true}),
@@ -88,7 +86,7 @@
// we attempt to find the actual target node
target = enyo.dom.byId(target) || enyo.getPath(target);
if (target) return target;
- // if we can't find the target we can't render it into anything
+ // if we can't find the target, we can't render it into anything;
// better to find out now
throw this.kindName + " cannot find the render target: " + this.renderTarget;
}, "renderTarget", {cached: true}),
@@ -98,29 +96,28 @@
//*@public
/**
- Call this method to render the controllers view into the
- DOM. If the view is already in the DOM it will re-render
- the element in place.
+ Renders the controller's view into the DOM. If the view is already
+ in the DOM, the element is re-rendered in place.
*/
render: function () {
// instance of the view
var view = this.view;
var target = this.get("_render_target");
- // if the view already has a DOM node we don't need to
+ // if the view already has a DOM node, we don't need to
// attempt to re-insert it
if (view.hasNode()) {
view.render();
} else {
- // otherwise we need to render it into the DOM
+ // otherwise, we need to render it into the DOM
view.renderInto(target);
}
},
//*@public
/**
- This method will immediately render the controller's view
- into the target passed in (either a node reference or string
- representing a node id attribute in the DOM).
+ Immediately renders the controller's view into the passed-in target
+ (either a node reference or s string representing a node id attribute
+ in the DOM).
*/
renderInto: function (target) {
// update the render target for the controller
@@ -138,7 +135,7 @@
// ensure we have created the view instance, note that
// this is done here _prior_ to mixin initialization
// (which takes place after all construction is done)
- // but this allows sub kinds to overload the constructed
+ // but this allows subkinds to overload the constructed
// method to control the flow
this._create_view();
},
View
22 source/kernel/dev.js
@@ -10,21 +10,21 @@
// we have to check whether or not the browser has supplied a valid
// method to use
var perf = window.performance || {};
- // test against all known vender-specific implementations but use
+ // test against all known vendor-specific implementations, but use
// a fallback just in case
perf.now = perf.now || perf.mozNow || perf.msNow || perf.oNow || perf.webkitNow || enyo.now;
- // while we do supply the fallback it forces a warning to indicate it
+ // while we do supply the fallback, it forces a warning to indicate it
// should not be trusted
if (perf.now === enyo.now) {
return function () {
enyo.warn(
"Performance benchmarking requested but was not available, " +
- "the tests using the method cause considerable overhead thus " +
+ "the tests using the method cause considerable overhead, thus " +
"skewing the results."
);
return perf.now();
};
- // otherwise we now have a pointer to the performant benchmark method
+ // otherwise, we now have a pointer to the performant benchmark method
} else return function () {return perf.now();};
}());
@@ -32,18 +32,18 @@
/**
This is a collection of methods to assist in simple benchmarking.
The goal was to supply useful functionality while impacting the results
- as little as possible (the more calculations we do during benchmarking
+ as little as possible (the more calculations we do during benchmarking,
the greater the opportunity to skew results). This is particularly important
- when using potentially nested benchmark series (benchmarking a method that
- executes other benchmarked methods).
+ when using potentially-nested benchmark series (i.e., benchmarking a method
+ that executes other benchmarked methods).
*/
- // track the active tests
+ // Track the active tests
var tests = {};
- // track averages
+ // Track averages
var averages = {};
- // default report template string
+ // Default report template string
var report_template = "- - - - - - - - - - - - - - - - -\n" +
"BENCHMARK REPORT (%.): %.\n" +
"TOTAL TIME: %.\n" +
@@ -51,7 +51,7 @@
"NUMBER OF ENTRIES: %.\n" +
"- - - - - - - - - - - - - - - - -\n";
- // calculates average and basic statistics
+ // Calculates average and basic statistics.
var calc = function (numbers) {
var total = 0;
var number = numbers.length;
Please sign in to comment.
Something went wrong with that request. Please try again.