[Doc Canary] Updated Ember namespace documentation.

(cherry picked from commit 01db4c5)

packages/ember-metal/lib/core.js

@@ -6,19 +6,17 @@
 */
 
 /**
-  All Ember methods and functions are defined inside of this namespace. You
-  generally should not add new properties to this namespace as it may be
-  overwritten by future versions of Ember.
+  This namespace contains all Ember methods and functions. Future versions of
+  Ember may overwrite this namespace and therefore, you should avoid adding any
+  new properties.
 
   You can also use the shorthand `Em` instead of `Ember`.
 
-  Ember-Runtime is a framework that provides core functions for Ember including
-  cross-platform functions, support for property observing and objects. Its
-  focus is on small size and performance. You can use this in place of or
-  along-side other cross-platform libraries such as jQuery.
-
-  The core Runtime framework is based on the jQuery API with a number of
-  performance optimizations.
+  At the heart of Ember is Ember-Runtime, a set of core functions that provide
+  cross-platform compatibility and object property observing.  Ember-Runtime is
+  small and performance-focused so you can use it alongside other
+  cross-platform libraries such as jQuery. For more details, see
+  [Ember-Runtime](http://emberjs.com/api/modules/ember-runtime.html).
 
   @class Ember
   @static
@@ -48,6 +46,8 @@ Ember.toString = function() { return 'Ember'; };
 
 
 /**
+  The semantic version.
+
   @property VERSION
   @type String
   @default 'VERSION_STRING_PLACEHOLDER'
@@ -56,11 +56,11 @@ Ember.toString = function() { return 'Ember'; };
 Ember.VERSION = 'VERSION_STRING_PLACEHOLDER';
 
 /**
-  Standard environmental variables. You can define these in a global `EmberENV`
-  variable before loading Ember to control various configuration settings.
-
-  For backwards compatibility with earlier versions of Ember the global `ENV`
-  variable will be used if `EmberENV` is not defined.
+  The hash of environment variables used to control various configuration
+  settings. To specify your own or override default settings, add the
+  desired properties to a global hash named `EmberENV` (or `ENV` for
+  backwards compatibility with earlier versions of Ember). The `EmberENV`
+  hash must be created before loading Ember.
 
   @property ENV
   @type Hash
@@ -85,9 +85,11 @@ if ('undefined' === typeof Ember.ENV.DISABLE_RANGE_API) {
 }
 
 /**
-  Hash of enabled Canary features. Add to this before creating your application.
+  The hash of enabled Canary features. Add to this, any canary features
+  before creating your application.
 
-  You can also define `EmberENV.FEATURES` if you need to enable features flagged at runtime.
+  Alternatively (and recommended), you can also define `EmberENV.FEATURES`
+  if you need to enable features flagged at runtime.
 
   @class FEATURES
   @namespace Ember
@@ -105,8 +107,8 @@ if (Ember.ENV.FEATURES) {
 }
 
 /**
-  Test that a feature is enabled. Parsed by Ember's build tools to leave
-  experimental features out of beta/stable builds.
+  Determine whether the specified `feature` is enabled. Used by Ember's
+  build tools to exclude experimental features from beta/stable builds.
 
   You can define the following configuration options:
 
@@ -115,7 +117,7 @@ if (Ember.ENV.FEATURES) {
     enabled/disabled.
 
   @method isEnabled
-  @param {String} feature
+  @param {String} feature The feature to check
   @return {Boolean}
   @for Ember.FEATURES
   @since 1.1.0
@@ -140,14 +142,17 @@ Ember.FEATURES.isEnabled = function(feature) {
 //
 
 /**
-  Determines whether Ember should enhance some built-in object prototypes to
-  provide a more friendly API. If enabled, a few methods will be added to
-  `Function`, `String`, and `Array`. `Object.prototype` will not be enhanced,
-  which is the one that causes most trouble for people.
+  Determines whether Ember should add to `Array`, `Function`, and `String`
+  native object prototypes, a few extra methods in order to provide a more
+  friendly API.
+
+  We generally recommend leaving this option set to true however, if you need
+  to turn it off, you can add the configuration property
+  `EXTEND_PROTOTYPES` to `EmberENV` and set it to `false`.
 
-  In general we recommend leaving this option set to true since it rarely
-  conflicts with other code. If you need to turn it off however, you can
-  define an `EmberENV.EXTEND_PROTOTYPES` config to disable it.
+  Note, when disabled (the default configuration for Ember Addons), you will
+  instead have to access all methods and functions from the Ember
+  namespace.
 
   @property EXTEND_PROTOTYPES
   @type Boolean
@@ -161,7 +166,8 @@ if (typeof Ember.EXTEND_PROTOTYPES === 'undefined') {
 }
 
 /**
-  Determines whether Ember logs a full stack trace during deprecation warnings
+  The `LOG_STACKTRACE_ON_DEPRECATION` property, when true, tells Ember to log
+  a full stack trace during deprecation warnings.
 
   @property LOG_STACKTRACE_ON_DEPRECATION
   @type Boolean
@@ -170,7 +176,8 @@ if (typeof Ember.EXTEND_PROTOTYPES === 'undefined') {
 Ember.LOG_STACKTRACE_ON_DEPRECATION = (Ember.ENV.LOG_STACKTRACE_ON_DEPRECATION !== false);
 
 /**
-  Determines whether Ember should add ECMAScript 5 Array shims to older browsers.
+  The `SHIM_ES5` property, when true, tells Ember to add ECMAScript 5 Array
+  shims to older browsers.
 
   @property SHIM_ES5
   @type Boolean
@@ -179,7 +186,8 @@ Ember.LOG_STACKTRACE_ON_DEPRECATION = (Ember.ENV.LOG_STACKTRACE_ON_DEPRECATION !
 Ember.SHIM_ES5 = (Ember.ENV.SHIM_ES5 === false) ? false : Ember.EXTEND_PROTOTYPES;
 
 /**
-  Determines whether Ember logs info about version of used libraries
+  The `LOG_VERSION` property, when true, tells Ember to log versions of all
+  dependent libraries in use.
 
   @property LOG_VERSION
   @type Boolean
@@ -188,7 +196,7 @@ Ember.SHIM_ES5 = (Ember.ENV.SHIM_ES5 === false) ? false : Ember.EXTEND_PROTOTYPE
 Ember.LOG_VERSION = (Ember.ENV.LOG_VERSION === false) ? false : true;
 
 /**
-  Empty function. Useful for some operations. Always returns `this`.
+  An empty function useful for some operations. Always returns `this`.
 
   @method K
   @private