sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/datastore/system/nested_store.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -11,13 +11,13 @@ sc_require('system/store');
   @class
 
   A nested store can buffer changes to a parent store and then commit them
-  all at once.  You usually will use a NestedStore as part of store chaining
+  all at once.  You usually will use a `NestedStore` as part of store chaining
   to stage changes to your object graph before sharing them with the rest of
   the application.
   
   Normally you will not create a nested store directly.  Instead, you can 
-  retrieve a nested store by using the chain() method.  When you are finished
-  working with the nested store, destroy() will dispose of it.
+  retrieve a nested store by using the `chain()` method.  When you are finished
+  working with the nested store, `destroy()` will dispose of it.
   
   @extends SC.Store
   @since SproutCore 1.0
@@ -29,7 +29,7 @@ SC.NestedStore = SC.Store.extend(
     This is set to YES when there are changes that have not been committed 
     yet.
 
-    @property {Boolean}
+    @type Boolean
     @default NO
   */
   hasChanges: NO,
@@ -37,17 +37,19 @@ SC.NestedStore = SC.Store.extend(
   /**
     The parent store this nested store is chained to.  Nested stores must have
     a parent store in order to function properly.  Normally, you create a 
-    nested store using the SC.Store#chain() method and this property will be
+    nested store using the `SC.Store#chain()` method and this property will be
     set for you.
     
-    @property {SC.Store}
+    @type SC.Store
+    @default null
   */
   parentStore: null,
 
   /**
-    YES if the view is nested. Walk like a duck
+    `YES` if the view is nested. Walk like a duck
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   isNested: YES,
 
@@ -57,7 +59,7 @@ SC.NestedStore = SC.Store.extend(
     then change the record in the parent store, the changes will not be 
     visible to your nested store until you commit or discard changes.
     
-    If NO, then the attribute hash will lock only when you write data.
+    If `NO`, then the attribute hash will lock only when you write data.
     
     Normally you want to lock your attribute hash the first time you read it.
     This will make your nested store behave most consistently.  However, if
@@ -67,7 +69,8 @@ SC.NestedStore = SC.Store.extend(
     ensuring that the sibling stores do not edit the same part of the object
     graph at the same time.
     
-    @property {Boolean} 
+    @type Boolean
+    @default YES
   */
   lockOnRead: YES,
 
@@ -85,7 +88,8 @@ SC.NestedStore = SC.Store.extend(
     Note that this is kept as an array because it will be stored as a dense 
     array on some browsers, making it faster.
     
-    @property {Array}
+    @type Array
+    @default null
   */
   locks: null,
 
@@ -95,7 +99,8 @@ SC.NestedStore = SC.Store.extend(
     chained stores.  For a log changes that may actually be committed back to
     the server see the changelog property.
     
-    @property {SC.Set}
+    @type SC.Set
+    @default YES
   */
   chainedChanges: null,
     
@@ -104,10 +109,11 @@ SC.NestedStore = SC.Store.extend(
   // 
   
   /**
-    find() cannot accept REMOTE queries in a nested store.  This override will
-    verify that condition for you.  See SC.Store#find() for info on using this
+    `find()` cannot accept REMOTE queries in a nested store.  This override will
+    verify that condition for you.  See `SC.Store#find()` for info on using this
     method.
     
+    @param {SC.Query} query query object to use.
     @returns {SC.Record|SC.RecordArray}
   */
   find: function(query) {
@@ -181,11 +187,9 @@ SC.NestedStore = SC.Store.extend(
 
   /**
     Resets a store's data hash contents to match its parent.
-    
-    @returns {SC.Store} receiver
   */
   reset: function() {
-
+    var nRecords, nr, sk;
     // requires a pstore to reset
     var parentStore = this.get('parentStore');
     if (!parentStore) throw SC.Store.NO_PARENT_STORE_ERROR;
@@ -195,6 +199,10 @@ SC.NestedStore = SC.Store.extend(
     this.revisions  = SC.beget(parentStore.revisions);
     this.statuses   = SC.beget(parentStore.statuses);
     
+    // beget nested records references
+    this.childRecords = parentStore.childRecords ? SC.beget(parentStore.childRecords) : {};
+    this.parentRecords = parentStore.parentRecords ? SC.beget(parentStore.parentRecords) : {};
+    
     // also, reset private temporary objects
     this.chainedChanges = this.locks = this.editables = null;
     this.changelog = null ;
@@ -215,7 +223,7 @@ SC.NestedStore = SC.Store.extend(
   },
 
   /**
-    Returns the SC.Error object associated with a specific record.
+    Returns the `SC.Error` object associated with a specific record.
 
     Delegates the call to the parent store.
 
@@ -229,7 +237,7 @@ SC.NestedStore = SC.Store.extend(
   },
 
   /**
-    Returns the SC.Error object associated with a specific query.
+    Returns the `SC.Error` object associated with a specific query.
 
     Delegates the call to the parent store.
 
@@ -250,8 +258,8 @@ SC.NestedStore = SC.Store.extend(
   // to use these methods.
   
   /**
-    Returns the current edit status of a storekey.  May be one of INHERITED,
-    EDITABLE, and LOCKED.  Used mostly for unit testing.
+    Returns the current edit status of a storekey.  May be one of `INHERITED`,
+    `EDITABLE`, and `LOCKED`.  Used mostly for unit testing.
     
     @param {Number} storeKey the store key
     @returns {Number} edit status
@@ -266,7 +274,8 @@ SC.NestedStore = SC.Store.extend(
     store.
   */
   _lock: function(storeKey) {
-    var locks = this.locks, rev, editables;
+    var locks = this.locks, rev, editables, 
+        pk, pr, path, tup, obj, key;
     
     // already locked -- nothing to do
     if (locks && locks[storeKey]) return this;
@@ -288,7 +297,24 @@ SC.NestedStore = SC.Store.extend(
     }
     
     if (pstore && editState === SC.Store.EDITABLE) {
-      this.dataHashes[storeKey] = SC.clone(pstore.dataHashes[storeKey], YES);
+      
+      pk = this.childRecords[storeKey];
+      if (pk){
+        // Since this is a nested record we have to actually walk up the parent chain
+        // to get to the root parent and clone that hash. And then reconstruct the 
+        // memory space linking.
+        this._lock(pk);
+        pr = this.parentRecords[pk];
+        if (pr) {
+          path = pr[storeKey];
+          tup = path ? SC.tupleForPropertyPath(path, this.dataHashes[pk]) : null;
+          if (tup){ obj = tup[0]; key = tup[1]; }
+          this.dataHashes[storeKey] = obj && key ? obj[key] : null;
+        }
+      }
+      else {
+        this.dataHashes[storeKey] = SC.clone(pstore.dataHashes[storeKey], YES);
+      }
       if (!editables) editables = this.editables = [];
       editables[storeKey] = 1 ; // mark as editable
       
@@ -373,9 +399,8 @@ SC.NestedStore = SC.Store.extend(
     return sc_super();
   },
   
-  /** @private - book-keeping for a single data hash. */
+  /** @private - bookkeeping for a single data hash. */
   dataHashDidChange: function(storeKeys, rev, statusOnly, key) {
-    
     // update the revision for storeKey.  Use generateStoreKey() because that
     // gaurantees a universally (to this store hierarchy anyway) unique 
     // key value.

data/lib/frameworks/sproutcore/frameworks/datastore/system/query.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -14,136 +14,123 @@ sc_require('models/record');
   This permits you to perform queries on your data store,
   written in a SQL-like language. Here is a simple example:
     
-  {{{
-    q = SC.Query.create({
-      conditions: "firstName = 'Jonny' AND lastName = 'Cash'"
-    })
-  }}}
+      q = SC.Query.create({
+        conditions: "firstName = 'Jonny' AND lastName = 'Cash'"
+      })
     
-  You can check if a certain record matches the query by calling:
+  You can check if a certain record matches the query by calling
 
-  {{{
-    q.contains(record)
-  }}}
+      q.contains(record)
   
   To find all records of your store, that match query q, use findAll with
   query q as argument:
   
-  {{{
-    r = MyApp.store.findAll(q)
-  }}}
+      r = MyApp.store.findAll(q)
   
-  r will be a record array containing all matching records.
-  To limit the query to a record type of MyApp.MyModel,
+  `r` will be a record array containing all matching records.
+  To limit the query to a record type of `MyApp.MyModel`,
   you can specify the type as a property of the query like this:
   
-  {{{
-    q = SC.Query.create({ 
-      conditions: "firstName = 'Jonny' AND lastName = 'Cash'",
-      recordType: MyApp.MyModel 
-    })
-  }}}
+      q = SC.Query.create({ 
+        conditions: "firstName = 'Jonny' AND lastName = 'Cash'",
+        recordType: MyApp.MyModel 
+      })
   
-  Calling find() like above will now return only records of type t.
+  Calling `find()` like above will now return only records of type t.
   It is recommended to limit your query to a record type, since the query will
   have to look for matching records in the whole store, if no record type
   is given.
   
   You can give an order, which the resulting records should follow, like this:
   
-  {{{
-    q = SC.Query.create({ 
-      conditions: "firstName = 'Jonny' AND lastName = 'Cash'",
-      recordType: MyApp.MyModel,
-      orderBy: "lastName, year DESC" 
-    });
-  }}}
+      q = SC.Query.create({ 
+        conditions: "firstName = 'Jonny' AND lastName = 'Cash'",
+        recordType: MyApp.MyModel,
+        orderBy: "lastName, year DESC" 
+      });
   
   The default order direction is ascending. You can change it to descending
-  by writing DESC behind the property name like in the example above.
+  by writing `'DESC'` behind the property name like in the example above.
   If no order is given, or records are equal in respect to a given order,
   records will be ordered by guid.
 
-  h2. SproutCore Query Language
+  SproutCore Query Language
+  =====
   
   Features of the query language:
   
-  h4. Primitives:
+  Primitives:
 
-  - record properties
-  - null, undefined
-  - true, false
-  - numbers (integers and floats)
-  - strings (double or single quoted)
+   - record properties
+   - `null`, `undefined`
+   - `true`, `false`
+   - numbers (integers and floats)
+   - strings (double or single quoted)
   
-  h4. Parameters:
+  Parameters:
 
-  - %@ (wild card)
-  - {parameterName} (named parameter)
+   - `%@` (wild card)
+   - `{parameterName}` (named parameter)
 
   Wild cards are used to identify parameters by the order in which they appear 
   in the query string. Named parameters can be used when tracking the order 
   becomes difficult. Both types of parameters can be used by giving the 
   parameters as a property to your query object:
   
-  {{{
-    yourQuery.parameters = yourParameters
-  }}}
+      yourQuery.parameters = yourParameters
   
   where yourParameters should have one of the following formats:
 
-    for wild cards: [firstParam, secondParam, thirdParam]
-    for named params: {name1: param1, mane2: parma2}
+   * for wild cards: `[firstParam, secondParam, thirdParam]`
+   * for named params: `{name1: param1, mane2: parma2}`
 
   You cannot use both types of parameters in a single query!
   
-  h4. Operators:
+  Operators:
   
-  - =
-  - !=
-  - <
-  - <=
-  - >
-  - >=
-  - BEGINS_WITH (checks if a string starts with another one)
-  - ENDS_WITH   (checks if a string ends with another one)
-  - CONTAINS    (checks if a string contains another one, or if an object is in an array)
-  - MATCHES     (checks if a string is matched by a regexp,
-                you will have to use a parameter to insert the regexp)
-  - ANY         (checks if the thing on its left is contained in the array
-                on its right, you will have to use a parameter
-                to insert the array)
-  - TYPE_IS     (unary operator expecting a string containing the name 
-                of a Model class on its right side, only records of this type
-                will match)
+   - `=`
+   - `!=`
+   - `<`
+   - `<=`
+   - `>`
+   - `>=`
+   - `BEGINS_WITH` -- (checks if a string starts with another one)
+   - `ENDS_WITH` --   (checks if a string ends with another one)
+   - `CONTAINS` --    (checks if a string contains another one, or if an
+                      object is in an array)
+   - `MATCHES` --     (checks if a string is matched by a regexp,
+                      you will have to use a parameter to insert the regexp)
+   - `ANY` --         (checks if the thing on its left is contained in the array
+                      on its right, you will have to use a parameter
+                      to insert the array)
+   - `TYPE_IS` --     (unary operator expecting a string containing the name 
+                      of a Model class on its right side, only records of this
+                      type will match)
     
-  h4. Boolean Operators:
+  Boolean Operators:
   
-  - AND
-  - OR
-  - NOT
+   - `AND`
+   - `OR`
+   - `NOT`
   
-  h4. Parenthesis for grouping:
+  Parenthesis for grouping:
   
-  - ( and )
+   - `(` and `)`
 
 
-  h2. Adding Your Own Query Handlers
+  Adding Your Own Query Handlers
+  ---
 
   You can extend the query language with your own operators by calling:
 
-  {{{
-    SC.Query.registerQueryExtension('your_operator', your_operator_definition);
-  }}}
+      SC.Query.registerQueryExtension('your_operator', your_operator_definition);
 
   See details below. As well you can provide your own comparison functions
   to control ordering of specific record properties like this:
 
-  {{{
-    SC.Query.registerComparison(property_name, comparison_for_this_property);
-  }}}
+      SC.Query.registerComparison(property_name, comparison_for_this_property);
   
-  h2. Examples
+  Examples
   
   Some example queries:
   
@@ -165,7 +152,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   /** 
     Walk like a duck.
     
-    @property {Boolean}
+    @type Boolean
   */
   isQuery: YES,
   
@@ -173,20 +160,20 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     Unparsed query conditions.  If you are handling a query yourself, then 
     you will find the base query string here.
     
-    @property {String}
+    @type String
   */
   conditions:  null,
   
   /**
     Optional orderBy parameters.  This can be a string of keys, optionally
-    beginning with the strings "DESC " or "ASC " to select descending or 
+    beginning with the strings `"DESC "` or `"ASC "` to select descending or 
     ascending order.
     
     Alternatively, you can specify a comparison function, in which case the
     two records will be sent to it.  Your comparison function, as with any
     other, is expected to return -1, 0, or 1.
     
-    @property {String | Function}
+    @type String | Function
   */
   orderBy:     null,
   
@@ -195,7 +182,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     filter the kinds of records this query will work on.  You may either 
     set this to a single record type or to an array or set of record types.
     
-    @property {SC.Record}
+    @type SC.Record
   */
   recordType:  null,
   
@@ -203,15 +190,16 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     Optional array of multiple record types.  If the query accepts multiple 
     record types, this is how you can check for it.
     
-    @property {SC.Enumerable}
+    @type SC.Enumerable
   */
   recordTypes: null,
   
   /**
-    Returns the complete set of recordTypes matched by this query.  Includes
-    any named recordTypes plus their subclasses.
+    Returns the complete set of `recordType`s matched by this query.  Includes
+    any named `recordType`s plus their subclasses.
     
-    @property {SC.Enumerable}
+    @property
+    @type SC.Enumerable
   */
   expandedRecordTypes: function() {
     var ret = SC.CoreSet.create(), rt, q  ;
@@ -252,7 +240,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     the query conditions.  If you are handling the query manually, these 
     parameters will not be used.
     
-    @property {Hash}
+    @type Hash
   */
   parameters:  null,
   
@@ -260,57 +248,61 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     Indicates the location where the result set for this query is stored.  
     Currently the available options are:
     
-    - SC.Query.LOCAL: indicates that the query results will be automatically computed from the in-memory store.
-    - SC.Query.REMOTE: indicates that the query results are kept on a remote server and hence must be loaded from the DataSource.
+     - `SC.Query.LOCAL` -- indicates that the query results will be
+       automatically computed from the in-memory store.
+     - `SC.Query.REMOTE` -- indicates that the query results are kept on a
+       remote server and hence must be loaded from the `DataSource`.
     
-    The default setting for this property is SC.Query.LOCAL.  
+    The default setting for this property is `SC.Query.LOCAL`.  
     
-    Note that even if a query location is LOCAL, your DataSource will still
-    have its fetch() method called for the query.  For LOCAL queries, you 
-    won't need to explicitly provide the query result set; you can just load
-    records into the in-memory store as needed and let the query recompute 
-    automatically.
+    Note that even if a query location is `LOCAL`, your `DataSource` will
+    still have its `fetch()` method called for the query.  For `LOCAL`
+    queries, you  won't need to explicitly provide the query result set; you
+    can just load records into the in-memory store as needed and let the query
+    recompute automatically.
     
-    If your query location is REMOTE, then your DataSource will need to 
+    If your query location is `REMOTE`, then your `DataSource` will need to 
     provide the actual set of query results manually.  Usually you will only 
-    need to use a REMOTE query if you are retrieving a large data set and you
+    need to use a `REMOTE` query if you are retrieving a large data set and you
     don't want to pay the cost of computing the result set client side.
     
-    @property {String}
+    @type String
   */
   location: 'local', // SC.Query.LOCAL
   
   /**
     Another query that will optionally limit the search of records.  This is 
-    usually configured for you when you do find() from another record array.
+    usually configured for you when you do `find()` from another record array.
     
-    @property {SC.Query}
+    @type SC.Query
   */
   scope: null,
   
   
   /**
-    Returns YES if query location is Remote.  This is sometimes more 
+    Returns `YES` if query location is Remote.  This is sometimes more 
     convenient than checking the location.
     
-    @property {Boolean}
+		@property
+    @type Boolean
   */
   isRemote: function() {
     return this.get('location') === SC.Query.REMOTE;
   }.property('location').cacheable(),
 
   /**
-    Returns YES if query location is Local.  This is sometimes more 
+    Returns `YES` if query location is Local.  This is sometimes more 
     convenient than checking the location.
     
-    @property {Boolean}
+		@property
+    @type Boolean
   */
   isLocal: function() {
     return this.get('location') === SC.Query.LOCAL;
   }.property('location').cacheable(),
   
   /**
-    Indicates whether a record is editable or not.  Defaults to NO.  Local
+    Indicates whether a record is editable or not.  Defaults to `NO`.  Local
     queries should never be made editable.  Remote queries may be editable or
     not depending on the data source.
   */
@@ -321,7 +313,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   // 
   
   /** 
-    Returns YES if record is matched by the query, NO otherwise.  This is 
+    Returns `YES` if record is matched by the query, `NO` otherwise.  This is 
     used when computing a query locally.  
  
     @param {SC.Record} record the record to check
@@ -355,7 +347,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   },
   
   /**
-    Returns YES if the query matches one or more of the record types in the
+    Returns `YES` if the query matches one or more of the record types in the
     passed set.
     
     @param {SC.Set} types set of record types
@@ -378,7 +370,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     Returns the sort order of the two passed records, taking into account the
     orderBy property set on this query.  This method does not verify that the
     two records actually belong in the query set or not; this is checked using
-    contains().
+    `contains()`.
  
     @param {SC.Record} record1 the first record
     @param {SC.Record} record2 the second record
@@ -445,9 +437,9 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   
   /**
     This method has to be called before the query object can be used.
-    You will normaly not have to do this, it will be called automatically
+    You will normaly not have to do this; it will be called automatically
     if you try to evaluate a query.
-    You can however use this function for testing your queries.
+    You can, however, use this function for testing your queries.
  
     @returns {Boolean} true if parsing succeeded, false otherwise
   */
@@ -494,10 +486,10 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   /** @private
     Properties that need to be copied when cloning the query.
   */
-  copyKeys: 'conditions orderBy recordType recordTypes parameters location scope'.w(),
+  copyKeys: ['conditions', 'orderBy', 'recordType', 'recordTypes', 'parameters', 'location', 'scope'],
   
   /** @private */
-  concatenatedProperties: 'copyKeys'.w(),
+  concatenatedProperties: ['copyKeys'],
 
   /** @private 
     Implement the Copyable API to clone a query object once it has been 
@@ -527,22 +519,38 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   
   /**
     This is the definition of the query language. You can extend it
-    by using SC.Query.registerQueryExtension().
+    by using `SC.Query.registerQueryExtension()`.
   */
   queryLanguage: {
     
     'UNKNOWN': {
       firstCharacter:   /[^\s'"\w\d\(\)\{\}]/,
-      notAllowed:       /[\s'"\w\d\(\)\{\}]/
+      notAllowed:       /[\-\s'"\w\d\(\)\{\}]/
     },
 
     'PROPERTY': {
       firstCharacter:   /[a-zA-Z_]/,
-      notAllowed:       /[^a-zA-Z_0-9]/,
+      notAllowed:       /[^a-zA-Z_0-9\.]/,
       evalType:         'PRIMITIVE',
       
       /** @ignore */
-      evaluate:         function (r,w) { return r.get(this.tokenValue); }
+      evaluate:         function (r,w) {
+                          var tokens = this.tokenValue.split('.');
+
+                          var len = tokens.length;
+                          if (len < 2) return r.get(this.tokenValue);
+
+                          var ret = r;
+                          for (var i = 0; i < len; i++) {
+                            if (!ret) return;
+                            if (ret.get) {
+                              ret = ret.get(tokens[i]);
+                            } else {
+                              ret = ret[tokens[i]];
+                            }
+                          }
+                          return ret;
+                        }
     },
 
     'NUMBER': {
@@ -878,7 +886,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   
   /**
     Takes a string and tokenizes it based on the grammar definition
-    provided. Called by parse().
+    provided. Called by `parse()`.
     
     @param {String} inputString the string to tokenize
     @param {Object} grammar the grammar definition (normally queryLanguage)
@@ -1026,11 +1034,11 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
     specified tree logic. The returned object will have an error property
     if building of the tree failed. Check it to get some information
     about what happend.
-    If everything worked the tree can be evaluated by calling:
+    If everything worked, the tree can be evaluated by calling
     
-      tree.evaluate(record, parameters)
+        tree.evaluate(record, parameters)
     
-    If tokenList is empty, a single token will be returned which will
+    If `tokenList` is empty, a single token will be returned which will
     evaluate to true for all records.
     
     @param {Array} tokenList the list of tokens
@@ -1191,7 +1199,7 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
   /**
     Takes a string containing an order statement and returns an array
     describing this order for easier processing.
-    Called by parse().
+    Called by `parse()`.
     
     @param {String | Function} orderOp the string containing the order statement, or a comparison function
     @returns {Array | Function} array of order statement, or a function if a function was specified
@@ -1226,22 +1234,22 @@ SC.Query = SC.Object.extend(SC.Copyable, SC.Freezable,
 SC.Query.mixin( /** @scope SC.Query */ {
 
   /** 
-    Constant used for SC.Query#location
+    Constant used for `SC.Query#location`
   
-    @property {String}
+    @type String
   */
   LOCAL: 'local',
   
   /** 
-    Constant used for SC.Query#location 
+    Constant used for `SC.Query#location`
     
-    @property {String}
+    @type String
   */
   REMOTE: 'remote',
   
   /**
-    Given a query, returns the associated storeKey.  For the inverse of this 
-    method see SC.Store.queryFor().
+    Given a query, returns the associated `storeKey`.  For the inverse of this 
+    method see `SC.Store.queryFor()`.
     
     @param {SC.Query} query the query
     @returns {Number} a storeKey.
@@ -1251,7 +1259,7 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
   
   /**
-    Will find which records match a give SC.Query and return an array of 
+    Will find which records match a give `SC.Query` and return an array of 
     store keys. This will also apply the sorting for the query.
     
     @param {SC.Query} query to apply
@@ -1275,7 +1283,7 @@ SC.Query.mixin( /** @scope SC.Query */ {
   
   /** 
     Sorts a set of store keys according to the orderBy property
-    of the SC.Query.
+    of the `SC.Query`.
     
     @param {Array} storeKeys to sort
     @param {SC.Query} query to use for sorting
@@ -1309,9 +1317,9 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
   
   /** 
-    Default sort method that is used when calling containsStoreKeys()
-    or containsRecords() on this query. Simply materializes two records based 
-    on storekeys before passing on to compare() .
+    Default sort method that is used when calling `containsStoreKeys()`
+    or `containsRecords()` on this query. Simply materializes two records
+    based on `storekey`s before passing on to `compare()`.
  
     @param {Number} storeKey1 a store key
     @param {Number} storeKey2 a store key
@@ -1385,48 +1393,42 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
   
   /**
-    Returns a SC.Query instance reflecting the passed properties.  Where 
+    Returns a `SC.Query` instance reflecting the passed properties.  Where 
     possible this method will return cached query instances so that multiple 
     calls to this method will return the same instance.  This is not possible 
     however, when you pass custom parameters or set ordering. All returned 
     queries are frozen.
     
     Usually you will not call this method directly.  Instead use the more
-    convenient SC.Query.local() and SC.Query.remote().
+    convenient `SC.Query.local()` and `SC.Query.remote()`.
     
-    h2. Examples
+    Examples
     
     There are a number of different ways you can call this method.  
     
     The following return local queries selecting all records of a particular 
     type or types, including any subclasses:
     
-    {{{
-      var people = SC.Query.local(Ab.Person);
-      var peopleAndCompanies = SC.Query.local([Ab.Person, Ab.Company]);
+        var people = SC.Query.local(Ab.Person);
+        var peopleAndCompanies = SC.Query.local([Ab.Person, Ab.Company]);
       
-      var people = SC.Query.local('Ab.Person');
-      var peopleAndCompanies = SC.Query.local('Ab.Person Ab.Company'.w());
+        var people = SC.Query.local('Ab.Person');
+        var peopleAndCompanies = SC.Query.local('Ab.Person Ab.Company'.w());
       
-      var allRecords = SC.Query.local(SC.Record);
-    }}} 
+        var allRecords = SC.Query.local(SC.Record);
     
     The following will match a particular type of condition:
     
-    {{{
-      var married = SC.Query.local(Ab.Person, "isMarried=YES");
-      var married = SC.Query.local(Ab.Person, "isMarried=%@", [YES]);
-      var married = SC.Query.local(Ab.Person, "isMarried={married}", {
-        married: YES
-      });
-    }}}
+        var married = SC.Query.local(Ab.Person, "isMarried=YES");
+        var married = SC.Query.local(Ab.Person, "isMarried=%@", [YES]);
+        var married = SC.Query.local(Ab.Person, "isMarried={married}", {
+          married: YES
+        });
     
     You can also pass a hash of options as the second parameter.  This is 
     how you specify an order, for example:
     
-    {{{
-      var orderedPeople = SC.Query.local(Ab.Person, { orderBy: "firstName" });
-    }}}
+        var orderedPeople = SC.Query.local(Ab.Person, { orderBy: "firstName" });
     
     @param {String} location the query location.
     @param {SC.Record|Array} recordType the record type or types.
@@ -1516,8 +1518,8 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
   
   /**
-    Returns a LOCAL query with the passed options.  For a full description of
-    the parameters you can pass to this method, see SC.Query.build().
+    Returns a `LOCAL` query with the passed options.  For a full description of
+    the parameters you can pass to this method, see `SC.Query.build()`.
   
     @param {SC.Record|Array} recordType the record type or types.
     @param {String} conditions optional conditions
@@ -1529,8 +1531,8 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
   
   /**
-    Returns a REMOTE query with the passed options.  For a full description of
-    the parameters you can pass to this method, see SC.Query.build().
+    Returns a `REMOTE` query with the passed options.  For a full description of
+    the parameters you can pass to this method, see `SC.Query.build()`.
     
     @param {SC.Record|Array} recordType the record type or types.
     @param {String} conditions optional conditions
@@ -1542,7 +1544,7 @@ SC.Query.mixin( /** @scope SC.Query */ {
   },
   
   /** @private 
-    called by SC.Record.extend(). invalided expandedRecordTypes
+    called by `SC.Record.extend()`. invalidates `expandedRecordTypes`
   */
   _scq_didDefineRecordType: function() {
     var q = SC.Query._scq_queriesWithExpandedRecordTypes;
@@ -1582,7 +1584,7 @@ SC.Query.registerComparison = function(propertyName, comparison) {
   You shoud provide a name for your extension and a definition
   specifying how it should be parsed and evaluated.
   
-  Have a look at queryLanguage for examples of definitions.
+  Have a look at `queryLanguage` for examples of definitions.
   
   TODO add better documentation here