Various documentation corrections

dom/route/route.js

@@ -390,8 +390,9 @@ function( $ ) {
 			}, props)) + ">" + name + "</a>";
 		},
 		/**
-		 * Returns if the options represent the current page.
+		 * Returns true if the options represent the current page.
 		 * @param {Object} options
+         * @return {Boolean}
 		 */
 		current: function( options ) {
 			return location.hash == "#!" + $route.param(options)

dom/selection/selection.js

@@ -195,7 +195,7 @@ getCharElement = function( elems , range, len ) {
  * returns an object with:
  * 
  *   - __start__ - The number of characters from the start of the element to the start of the selection.
- *   - __end__ - The number of characters from teh start of the element to the end of the selection.
+ *   - __end__ - The number of characters from the start of the element to the end of the selection.
  *   - __range__ - A [jQuery.Range $.Range] that represents the current selection.
  * 
  * This lets you get the selected text in a textarea like:

lang/string/string.js

@@ -89,7 +89,7 @@ steal('jquery').then(function( $ ) {
 			 * 'object path' by removing or adding properties.
 			 * 
 			 *     Foo = {Bar: {Zar: {"Ted"}}}
-		 	 *     $.String.getobject("Foo.Bar.Zar") //-> "Ted"
+		 	 *     $.String.getObject("Foo.Bar.Zar") //-> "Ted"
 			 * 
 			 * @param {String} name the name of the object to look for
 			 * @param {Array} [roots] an array of root objects to look for the 

lang/vector/vector.js

@@ -77,28 +77,36 @@ steal('jquery').then(function($){
 			}
 			return vec.update(arr);
 		},
-/*
-	 * Returns the 2nd value of the vector
-	 * @return {Number}
-	 */
+		/**
+		 * Returns the first value of the vector
+		 * @return {Number}
+		 */
 		x: getSetZero,
-		width: getSetZero,
+		/**
+		 * same as x()
+		 * @return {Number}
+		 */
+		left: getSetZero,
 		/**
 		 * Returns the first value of the vector
 		 * @return {Number}
 		 */
+		width: getSetZero,
+		/**
+		 * Returns the 2nd value of the vector
+		 * @return {Number}
+		 */
 		y: getSetOne,
-		height: getSetOne,
 		/**
-		 * Same as x()
+		 * Same as y()
 		 * @return {Number}
 		 */
 		top: getSetOne,
 		/**
-		 * same as y()
+		 * Returns the 2nd value of the vector
 		 * @return {Number}
 		 */
-		left: getSetZero,
+		height: getSetOne,
 		/**
 		 * returns (x,y)
 		 * @return {String}

model/list/list.js

@@ -5,8 +5,7 @@ steal('jquery/model').then(function( $ ) {
 			return args[0]
 		} else if ( args[0] instanceof $.Model.List ) {
 			return $.makeArray(args[0])
-		}
-		else {
+		} else {
 			return $.makeArray(args)
 		}
 	},
@@ -447,7 +446,8 @@ steal('jquery/model').then(function( $ ) {
 		 * 
 		 *     var match = list.get($('#content')[0])
 		 * 
-		 * @param {Object} args element or id to remove
+		 * @param {Object} args elements or ids to retrieve.
+         * @return {$.Model.List} A sub-Model.List with the elements that were queried.
 		 */
 		get: function() {
 			if (!this.length ) {
@@ -465,8 +465,10 @@ steal('jquery/model').then(function( $ ) {
 
 			for ( var i = 0; i < args.length; i++ ) {
 				if ( args[i].nodeName && (matches = args[i].className.match(test)) ) {
+                // If this is a dom element
 					val = this._data[matches[1]]
 				} else {
+                // Else an id was provided as a number or string.
 					val = this._data[typeof args[i] == 'string' || typeof args[i] == 'number' ? args[i] : args[i][idName]]
 				}
 				val && list.push(val)
@@ -478,13 +480,14 @@ steal('jquery/model').then(function( $ ) {
 		 *
 		 * To remove by id:
 		 *
-		 *     var match = list.get(23);
+		 *     var match = list.remove(23);
 		 *
 		 * or to remove by element:
 		 * 
-		 *     var match = list.get($('#content')[0])
+		 *     var match = list.remove($('#content')[0])
 		 *
-		 * @param {Object} args element or id to remove
+		 * @param {Object} args elements or ids to remove.
+         * @return {$.Model.List} A Model.List of the elements that were removed.
 		 */
 		remove: function( args ) {
 			if (!this.length ) {
@@ -691,13 +694,15 @@ steal('jquery/model').then(function( $ ) {
 		},
 		/**
 		 * @function push
-		 * Adds a instance or instances to the list
+		 * Adds an instance or instances to the list
 		 * 
 		 *     list.push(new Recipe({id: 5, name: "Water"}))
+         *     
+         * @param args {Object} The instance(s) to push onto the list.
+         * @return {Number} The number of elements in the list after the new element was pushed in.
 		 */
 		push: function() {
-			var args = getArgs(arguments),
-				self = this;
+			var args = getArgs(arguments);
 			//listen to events on this only if someone is listening on us, this means remove won't
 			//be called if we aren't listening for removes
 			if ( this[expando] !== undefined ) {

model/model.js

@@ -835,6 +835,11 @@ steal('jquery/class', 'jquery/lang/string', function() {
 		 * <code>Task.models</code> and <code>Person.model</code>
 		 * to convert the raw data into an array of Tasks and a Person.
 		 * 
+		 * Note that the full names of the models themselves are <code>App.Models.Task</code>
+		 * and <code>App.Models.Person</code>. The _.model_ and _.models_ parts are appended
+		 * for the benefit of [jQuery.Model.static.convert convert] to identify the types as 
+		 * models.
+		 * 
 		 * @demo jquery/model/pages/associations.html
 		 * 
 		 */

model/validations/validations.js

@@ -68,7 +68,7 @@ $.extend($.Model, {
    /**
     * @function jQuery.Model.static.validate
     * @parent jquery.model.validations
-    * Validates each of the specified attributes with the given function.  See [validation] for more on validations.
+    * Validates each of the specified attributes with the given function.  See [jquery.model.validations validation] for more on validations.
     * @param {Array|String} attrNames Attribute name(s) to to validate
     * @param {Function} validateProc Function used to validate each given attribute. Returns nothing if valid and an error message otherwise. Function is called in the instance context and takes the value to validate.
     * @param {Object} options (optional) Options for the validations.  Valid options include 'message' and 'testIf'.
@@ -91,8 +91,8 @@ $.extend($.Model, {
     *  * presence - "can't be empty"
     *  * range - "is out of range"
     * 
-    * It is important to ensure that you steal jquery/model/validations 
-    * before overwriting the messages, otherwise the changes will
+    * It is important to steal jquery/model/validations before 
+    * overwriting the messages, otherwise the changes will
     * be lost once steal loads it later.
     * 
     * ## Example
@@ -112,7 +112,7 @@ $.extend($.Model, {
     * @function jQuery.Model.static.validateFormatOf
     * @parent jquery.model.validations
     * Validates where the values of specified attributes are of the correct form by
-    * matching it against the regular expression provided.  See [validation] for more on validations.
+    * matching it against the regular expression provided.  See [jquery.model.validations validation] for more on validations.
     * @param {Array|String} attrNames Attribute name(s) to to validate
     * @param {RegExp} regexp Regular expression used to match for validation
     * @param {Object} options (optional) Options for the validations.  Valid options include 'message' and 'testIf'.
@@ -132,7 +132,7 @@ $.extend($.Model, {
     * @function jQuery.Model.static.validateInclusionOf
     * @parent jquery.model.validations
     * Validates whether the values of the specified attributes are available in a particular
-    * array.   See [validation] for more on validations.
+    * array.   See [jquery.model.validations validation] for more on validations.
     * @param {Array|String} attrNames Attribute name(s) to to validate
     * @param {Array} inArray Array of options to test for inclusion
     * @param {Object} options (optional) Options for the validations.  Valid options include 'message' and 'testIf'.
@@ -151,7 +151,7 @@ $.extend($.Model, {
    /**
     * @function jQuery.Model.static.validateLengthOf
     * @parent jquery.model.validations
-    * Validates that the specified attributes' lengths are in the given range.  See [validation] for more on validations.
+    * Validates that the specified attributes' lengths are in the given range.  See [jquery.model.validations validation] for more on validations.
     * @param {Array|String} attrNames Attribute name(s) to to validate
     * @param {Number} min Minimum length (inclusive)
     * @param {Number} max Maximum length (inclusive)
@@ -170,7 +170,7 @@ $.extend($.Model, {
    /**
     * @function jQuery.Model.static.validatePresenceOf
     * @parent jquery.model.validations
-    * Validates that the specified attributes are not blank.  See [validation] for more on validations.
+    * Validates that the specified attributes are not blank.  See [jquery.model.validations validation] for more on validations.
     * @param {Array|String} attrNames Attribute name(s) to to validate
     * @param {Object} options (optional) Options for the validations.  Valid options include 'message' and 'testIf'.
     *
@@ -185,7 +185,7 @@ $.extend($.Model, {
    /**
     * @function jQuery.Model.static.validateRangeOf
     * @parent jquery.model.validations
-    * Validates that the specified attributes are in the given numeric range.  See [validation] for more on validations.
+    * Validates that the specified attributes are in the given numeric range.  See [jquery.model.validations validation] for more on validations.
     * @param {Array|String} attrNames Attribute name(s) to to validate
     * @param {Number} low Minimum value (inclusive)
     * @param {Number} hi Maximum value (inclusive)