Refs #1049, #996, #1046, #1009, #1044: Fixed misc JS docs

http://source.rd.rcg.local/trac/eagle6/changeset/1274/Eagle6_SVN

lib/pipeline/FieldPath.js

@@ -1,9 +1,12 @@
 var FieldPath = module.exports = FieldPath = (function(){
 	// CONSTRUCTOR
-	/** Constructor for field paths.
-	| @param fieldPath the dotted field path string or non empty pre-split vector.
-	| The constructed object will have getPathLength() > 0.
-	| Uassert if any component field names do not pass validation.
+	/**
+	* Constructor for field paths.
+	*
+	* The constructed object will have getPathLength() > 0.
+	* Uassert if any component field names do not pass validation.
+	*
+	* @param fieldPath the dotted field path string or non empty pre-split vector.
 	**/
 	var klass = function FieldPath(path){
 		var fields = typeof(path) === "object" && typeof(path.length) === "number" ? path : path.split(".");
@@ -23,9 +26,11 @@ var FieldPath = module.exports = FieldPath = (function(){
 	klass.PREFIX = "$";
 
 	// PROTOTYPE MEMBERS
-	/** Get the full path.
-	| @param fieldPrefix whether or not to include the field prefix
-	| @returns the complete field path
+	/**
+	* Get the full path.
+	*
+	* @param fieldPrefix whether or not to include the field prefix
+	* @returns the complete field path
 	*/
 	proto.getPath = function getPath(withPrefix) {
 		return ( !! withPrefix ? FieldPath.PREFIX : "") + this.fields.join(".");
@@ -36,16 +41,20 @@ var FieldPath = module.exports = FieldPath = (function(){
 		return new FieldPath(this.fields.slice(1));
 	};
 
-	/** Get a particular path element from the path.
-	| @param i the zero based index of the path element.
-	| @returns the path element
+	/**
+	* Get a particular path element from the path.
+	*
+	* @param i the zero based index of the path element.
+	* @returns the path element
 	*/
 	proto.getFieldName = function getFieldName(i){	//TODO: eventually replace this with just using .fields[i] directly
 		return this.fields[i];
 	};
 
-	/** Get the number of path elements in the field path.
-	| @returns the number of path elements
+	/**
+	* Get the number of path elements in the field path.
+	*
+	* @returns the number of path elements
 	**/
 	proto.getPathLength = function getPathLength() {
 		return this.fields.length;

lib/pipeline/expressions/CompareExpression.js

@@ -15,10 +15,12 @@ var CompareExpression = module.exports = (function(){
 		FieldRangeExpression = require("./FieldRangeExpression");
 
 	// NESTED CLASSES
-	/**Lookup table for truth value returns
-	| @param truthValues	truth value for -1, 0, 1
-	| @param reverse		reverse comparison operator
-	| @param name			string name
+	/**
+	* Lookup table for truth value returns
+	*
+	* @param truthValues	truth value for -1, 0, 1
+	* @param reverse		reverse comparison operator
+	* @param name			string name
 	**/
 	var CmpLookup = (function(){	// emulating a struct
 		// CONSTRUCTOR

lib/pipeline/expressions/ConstantExpression.js

@@ -12,8 +12,10 @@ var ConstantExpression = module.exports = (function(){
 		return "$const";
 	};
 
-	/**Get the constant value represented by this Expression.
-	| @returns the value
+	/**
+	* Get the constant value represented by this Expression.
+	*
+	* @returns the value
 	**/
 	proto.getValue = function getValue(){	//TODO: convert this to an instance field rather than a property
 		return this.value;

lib/pipeline/expressions/Expression.js

@@ -139,13 +139,16 @@ var Expression = module.exports = (function(){
 		}
 	});
 
-	/** Parse an Object.  The object could represent a functional expression or a Document expression.
-	| @param obj	the element representing the object
-	| @param ctx	a MiniCtx representing the options above
-	| @returns the parsed Expression
-	| An object expression can take any of the following forms:
-	|	f0: {f1: ..., f2: ..., f3: ...}
-	|	f0: {$operator:[operand1, operand2, ...]}
+	/**
+	* Parse an Object.  The object could represent a functional expression or a Document expression.
+	*
+	* @param obj	the element representing the object
+	* @param ctx	a MiniCtx representing the options above
+	* @returns the parsed Expression
+	*
+	* An object expression can take any of the following forms:
+	*	f0: {f1: ..., f2: ..., f3: ...}
+	*	f0: {$operator:[operand1, operand2, ...]}
 	**/
 	klass.parseObject = function parseObject(obj, ctx){
 		if(!(ctx instanceof ObjectCtx)) throw new Error("ctx must be ObjectCtx");
@@ -203,10 +206,12 @@ var Expression = module.exports = (function(){
 		return expr;
 	};
 
-	/** Parse a BSONElement Object which has already been determined to be functional expression.
-	| @param opName	the name of the (prefix) operator
-	| @param obj	the BSONElement to parse
-	| @returns the parsed Expression
+	/**
+	* Parse a BSONElement Object which has already been determined to be functional expression.
+	*
+	* @param opName	the name of the (prefix) operator
+	* @param obj	the BSONElement to parse
+	* @returns the parsed Expression
 	**/
 	klass.parseExpression = function parseExpression(opName, obj) {
 		// look for the specified operator
@@ -240,9 +245,11 @@ var Expression = module.exports = (function(){
         return expr;
 	};
 
-	/** Parse a BSONElement which is an operand in an Expression.
-	| @param pBsonElement the expected operand's BSONElement
-	| @returns the parsed operand, as an Expression
+	/**
+	* Parse a BSONElement which is an operand in an Expression.
+	*
+	* @param pBsonElement the expected operand's BSONElement
+	* @returns the parsed operand, as an Expression
 	**/
 	klass.parseOperand = function parseOperand(obj){
 		var t = typeof(obj);
@@ -254,10 +261,12 @@ var Expression = module.exports = (function(){
 		else return new ConstantExpression(obj);
 	};
 
-	/** Produce a field path string with the field prefix removed.
-	| @param prefixedField the prefixed field
-	| @returns the field path with the prefix removed
-	| Throws an error if the field prefix is not present.
+	/**
+	* Produce a field path string with the field prefix removed.
+	* Throws an error if the field prefix is not present.
+	*
+	* @param prefixedField the prefixed field
+	* @returns the field path with the prefix removed
 	**/
 	klass.removeFieldPrefix = function removeFieldPrefix(prefixedField) {
 		if (prefixedField.indexOf("\0") != -1) throw new Error("field path must not contain embedded null characters; code 16419");
@@ -274,30 +283,39 @@ var Expression = module.exports = (function(){
 
 
 	// PROTOTYPE MEMBERS
-	/*** Evaluate the Expression using the given document as input.
-	| @returns the computed value
+	/***
+	* Evaluate the Expression using the given document as input.
+	*
+	* @returns the computed value
 	***/
 	proto.evaluate = function evaluate(obj) {
 		throw new Error("WAS NOT IMPLEMENTED BY INHERITOR!");
 	};
 
-	/** Optimize the Expression.
-	| This provides an opportunity to do constant folding, or to collapse nested
-	|  operators that have the same precedence, such as $add, $and, or $or.
-	| The Expression should be replaced with the return value, which may or may
-	|  not be the same object.  In the case of constant folding, a computed
-	|  expression may be replaced by a constant.
-	| @returns the optimized Expression
+	/**
+	* Optimize the Expression.
+	*
+	* This provides an opportunity to do constant folding, or to collapse nested
+	*  operators that have the same precedence, such as $add, $and, or $or.
+	*
+	* The Expression should be replaced with the return value, which may or may
+	*  not be the same object.  In the case of constant folding, a computed
+	*  expression may be replaced by a constant.
+	*
+	* @returns the optimized Expression
 	**/
 	proto.optimize = function optimize() {
 		throw new Error("WAS NOT IMPLEMENTED BY INHERITOR!");
 	};
 
-	/** Add this expression's field dependencies to the set Expressions are trees, so this is often recursive.
-	| @param deps	output parameter
-	| @param path	path to self if all ancestors are ExpressionObjects.
-	| Top-level ExpressionObject gets pointer to empty vector.
-	| If any other Expression is an ancestor, or in other cases where {a:1} inclusion objects aren't allowed, they get NULL.
+	/**
+	* Add this expression's field dependencies to the set Expressions are trees, so this is often recursive.
+	*
+	* Top-level ExpressionObject gets pointer to empty vector.
+	* If any other Expression is an ancestor, or in other cases where {a:1} inclusion objects aren't allowed, they get NULL.
+	*
+	* @param deps	output parameter
+	* @param path	path to self if all ancestors are ExpressionObjects.
 	**/
 	proto.addDependencies = function addDependencies(deps, path) {
 		throw new Error("WAS NOT IMPLEMENTED BY INHERITOR!");

lib/pipeline/expressions/FieldPathExpression.js

@@ -1,8 +1,9 @@
 var FieldPathExpression = module.exports = (function(){
 	// CONSTRUCTOR
-	/** Create a field path expression. Evaluation will extract the value
-	|	associated with the given field path from the source document.
-	| @param fieldPath the field path string, without any leading document indicator
+	/**
+	* Create a field path expression. Evaluation will extract the value associated with the given field path from the source document.
+	*
+	* @param fieldPath the field path string, without any leading document indicator
 	**/
 	var klass = function FieldPathExpression(path){
 		if(arguments.length !== 1) throw new Error("args expected: path");
@@ -17,16 +18,19 @@ var FieldPathExpression = module.exports = (function(){
 		return this._evaluatePath(obj, 0, this.path.fields.length);
 	};
 
-	/** Internal implementation of evaluate(), used recursively.
-	| The internal implementation doesn't just use a loop because of the
-	| possibility that we need to skip over an array.  If the path is "a.b.c",
-	| and a is an array, then we fan out from there, and traverse "b.c" for each
-	| element of a:[...].  This requires that a be an array of objects in order
-	| to navigate more deeply.
-	| @param index current path field index to extract
-	| @param pathLength maximum number of fields on field path
-	| @param pDocument current document traversed to (not the top-level one)
-	| @returns the field found; could be an array
+	/**
+	* Internal implementation of evaluate(), used recursively.
+	*
+	* The internal implementation doesn't just use a loop because of the
+	* possibility that we need to skip over an array.  If the path is "a.b.c",
+	* and a is an array, then we fan out from there, and traverse "b.c" for each
+	* element of a:[...].  This requires that a be an array of objects in order
+	* to navigate more deeply.
+	*
+	* @param index current path field index to extract
+	* @param pathLength maximum number of fields on field path
+	* @param pDocument current document traversed to (not the top-level one)
+	* @returns the field found; could be an array
 	**/
 	proto._evaluatePath = function _evaluatePath(obj, i, len){
 		var fieldName = this.path.fields[i],

lib/pipeline/expressions/FieldRangeExpression.js

@@ -1,18 +1,23 @@
 var FieldRangeExpression = module.exports = (function(){
 	// CONSTRUCTOR
-	/** Create a field range expression.
-	| Field ranges are meant to match up with classic Matcher semantics, and
-	| therefore are conjunctions.  For example, these appear in mongo shell
-	| predicates in one of these forms:
-	|	{ a : C } -> (a == C) // degenerate "point" range
-	|	{ a : { $lt : C } } -> (a < C) // open range
-	|	{ a : { $gt : C1, $lte : C2 } } -> ((a > C1) && (a <= C2)) // closed
-	| When initially created, a field range only includes one end of the range.  Additional points may be added via intersect().
-	| Note that NE and CMP are not supported.
-	| @param pathExpr the field path for extracting the field value
-	| @param cmpOp the comparison operator
-	| @param value the value to compare against
-	| @returns the newly created field range expression
+	/**
+	* Create a field range expression.
+	*
+	* Field ranges are meant to match up with classic Matcher semantics, and therefore are conjunctions.
+	*
+	* For example, these appear in mongo shell predicates in one of these forms:
+	*	{ a : C } -> (a == C) // degenerate "point" range
+	*	{ a : { $lt : C } } -> (a < C) // open range
+	*	{ a : { $gt : C1, $lte : C2 } } -> ((a > C1) && (a <= C2)) // closed
+	*
+	* When initially created, a field range only includes one end of the range.  Additional points may be added via intersect().
+	*
+	* Note that NE and CMP are not supported.
+	*
+	* @param pathExpr the field path for extracting the field value
+	* @param cmpOp the comparison operator
+	* @param value the value to compare against
+	* @returns the newly created field range expression
 	**/
 	var klass = function FieldRangeExpression(pathExpr, cmpOp, value){
 		if(arguments.length !== 3) throw new Error("args expected: pathExpr, cmpOp, and value");
@@ -141,14 +146,18 @@ var FieldRangeExpression = module.exports = (function(){
 		return this.pathExpr.addDependencies(deps);
 	};
 
-	/** Add an intersecting range.
-	| This can be done any number of times after creation.  The range is
-	| internally optimized for each new addition.  If the new intersection
-	| extends or reduces the values within the range, the internal
-	| representation is adjusted to reflect that.
-	| Note that NE and CMP are not supported.
-	| @param cmpOp the comparison operator
-	| @param pValue the value to compare against
+	/**
+	* Add an intersecting range.
+	*
+	* This can be done any number of times after creation.  The range is
+	* internally optimized for each new addition.  If the new intersection
+	* extends or reduces the values within the range, the internal
+	* representation is adjusted to reflect that.
+	*
+	* Note that NE and CMP are not supported.
+	*
+	* @param cmpOp the comparison operator
+	* @param pValue the value to compare against
 	**/
 	proto.intersect = function intersect(cmpOp, value){
 		this.range = this.range.intersect(new Range({cmpOp:cmpOp, value:value}));

lib/pipeline/expressions/NaryExpression.js

@@ -78,8 +78,10 @@ var NaryExpression = module.exports = (function(){
 		return deps;
 	};
 
-	/**Add an operand to the n-ary expression.
-	| @param pExpression the expression to add
+	/**
+	* Add an operand to the n-ary expression.
+	*
+	* @param pExpression the expression to add
 	**/
 	proto.addOperand = function addOperand(expr) {
 		this.operands.push(expr);
@@ -101,19 +103,21 @@ var NaryExpression = module.exports = (function(){
 //TODO:	proto.addToBsonObj  ?
 //TODO: proto.addToBsonArray  ?
 
-	/**Checks the current size of vpOperand; if the size equal to or
-	| greater than maxArgs, fires a user assertion indicating that this
-	| operator cannot have this many arguments.
-	| The equal is there because this is intended to be used in addOperand() to check for the limit *before* adding the requested argument.
-	| @param maxArgs the maximum number of arguments the operator accepts
+	/**
+	* Checks the current size of vpOperand; if the size equal to or greater than maxArgs, fires a user assertion indicating that this operator cannot have this many arguments.
+	* The equal is there because this is intended to be used in addOperand() to check for the limit *before* adding the requested argument.
+	*
+	* @param maxArgs the maximum number of arguments the operator accepts
 	**/
 	proto.checkArgLimit = function checkArgLimit(maxArgs) {
 		if (this.operands.length >= maxArgs) throw new Error(this.getOpName() + " only takes " + maxArgs + " operand" + (maxArgs == 1 ? "" : "s") + "; code 15993");
 	};
 
-	/**Checks the current size of vpOperand; if the size is not equal to reqArgs, fires a user assertion indicating that this must have exactly reqArgs arguments.
-	| This is meant to be used in evaluate(), *before* the evaluation takes place.
-	| @param reqArgs the number of arguments this operator requires
+	/**
+	* Checks the current size of vpOperand; if the size is not equal to reqArgs, fires a user assertion indicating that this must have exactly reqArgs arguments.
+	* This is meant to be used in evaluate(), *before* the evaluation takes place.
+	*
+	* @param reqArgs the number of arguments this operator requires
 	**/
 	proto.checkArgCount = function checkArgCount(reqArgs) {
 		if (this.operands.length !== reqArgs) throw new Error(this.getOpName() + ":  insufficient operands; " + reqArgs + " required, only got " + this.operands.length + "; code 15997");

lib/pipeline/expressions/ObjectExpression.js

@@ -25,9 +25,11 @@ var ObjectExpression = module.exports = (function(){
 
 	// PROTOTYPE MEMBERS
 
-	/** evaluate(), but return a Document instead of a Value-wrapped Document.
-	| @param pDocument the input Document
-	| @returns the result document
+	/**
+	* evaluate(), but return a Document instead of a Value-wrapped Document.
+	*
+	* @param pDocument the input Document
+	* @returns the result document
 	**/
 	proto.evaluateDocument = function evaluateDocument(doc){
 		throw new Error("FINISH evaluateDocument");	//TODO:...
@@ -93,10 +95,12 @@ var ObjectExpression = module.exports = (function(){
 		return deps;
 	};
 
-	/** evaluate(), but add the evaluated fields to a given document instead of creating a new one.
-	| @param pResult the Document to add the evaluated expressions to
-	| @param pDocument the input Document for this level
-	| @param rootDoc the root of the whole input document
+	/**
+	* evaluate(), but add the evaluated fields to a given document instead of creating a new one.
+	*
+	* @param pResult the Document to add the evaluated expressions to
+	* @param pDocument the input Document for this level
+	* @param rootDoc the root of the whole input document
 	**/
 	proto.addToDocument = function addToDocument(result, document, rootDoc){
 		throw new Error("FINISH addToDocument");	//TODO:...
@@ -236,9 +240,11 @@ var ObjectExpression = module.exports = (function(){
 		*/
 	};
 
-	/** Add a field to the document expression.
-	| @param fieldPath the path the evaluated expression will have in the result Document
-	| @param pExpression the expression to evaluate obtain this field's Value in the result Document
+	/**
+	* Add a field to the document expression.
+	*
+	* @param fieldPath the path the evaluated expression will have in the result Document
+	* @param pExpression the expression to evaluate obtain this field's Value in the result Document
 	**/
 	proto.addField = function addField(path, pExpression){
 		var fieldPart = path.fields[0],
@@ -307,16 +313,21 @@ var subObj = expr instanceof ObjectExpression ? expr : undefined;
 		*/
 	};
 
-	/** Add a field path to the set of those to be included.
-	| Note that including a nested field implies including everything on the path leading down to it.
-	| @param fieldPath the name of the field to be included
+	/**
+	* Add a field path to the set of those to be included.
+	*
+	* Note that including a nested field implies including everything on the path leading down to it.
+	*
+	* @param fieldPath the name of the field to be included
 	**/
 	proto.includePath = function includePath(path){
 		this.addField(path);
 	};
 
-	/** Get a count of the added fields.
-	| @returns how many fields have been added
+	/**
+	* Get a count of the added fields.
+	*
+	* @returns how many fields have been added
 	**/
 	proto.getFieldCount = function getFieldCount(){
 		var e; console.warn(e=new Error("CALLER SHOULD BE USING #expressions.length instead!")); console.log(e.stack);
@@ -342,10 +353,12 @@ var subObj = expr instanceof ObjectExpression ? expr : undefined;
 	}
 */
 
-/** Specialized BSON conversion that allows for writing out a $project specification.
-| This creates a standalone object, which must be added to a containing object with a name
-| @param pBuilder where to write the object to
-| @param requireExpression see Expression::addToBsonObj
+/**
+* Specialized BSON conversion that allows for writing out a $project specification.
+* This creates a standalone object, which must be added to a containing object with a name
+*
+* @param pBuilder where to write the object to
+* @param requireExpression see Expression::addToBsonObj
 **/
 //TODO:	proto.documentToBson = ...?
 //TODO:	proto.addToBsonObj = ...?