Merge pull request #17560 from WestLangley/dev_vector3

Vector3: Clarify zero vector use case

docs/api/en/math/Vector3.html

@@ -121,7 +121,7 @@ var d = a.distanceTo( b );
 
 		<h3>[method:Float angleTo]( [param:Vector3 v] )</h3>
 		<p>
-		Returns the angle between this vector and vector [page:Vector3 v] in radians.
+		Returns the angle between this vector and vector [page:Vector3 v] in radians. Neither this vector nor [page:Vector3 v] can be the zero vector.
 		</p>
 
 		<h3>[method:this ceil]()</h3>
@@ -320,8 +320,8 @@ var d = a.distanceTo( b );
 		normal from this vector.
 		</p>
 
-		<h3>[method:this projectOnVector]( [param:Vector3] )</h3>
-		<p>[link:https://en.wikipedia.org/wiki/Vector_projection Projects] this vector onto another vector.</p>
+		<h3>[method:this projectOnVector]( [param:Vector3 v] )</h3>
+		<p>[link:https://en.wikipedia.org/wiki/Vector_projection Projects] this vector onto [page:Vector3 v]. [page:Vector3 v] cannot be the zero vector.</p>
 
 		<h3>[method:this reflect]( [param:Vector3 normal] )</h3>
 		<p>

src/math/Vector3.js

@@ -526,11 +526,13 @@ Object.assign( Vector3.prototype, {
 
 	},
 
-	projectOnVector: function ( vector ) {
+	projectOnVector: function ( v ) {
 
-		var scalar = vector.dot( this ) / vector.lengthSq();
+		// v cannot be the zero v
 
-		return this.copy( vector ).multiplyScalar( scalar );
+		var scalar = v.dot( this ) / v.lengthSq();
+
+		return this.copy( v ).multiplyScalar( scalar );
 
 	},
 
@@ -553,6 +555,8 @@ Object.assign( Vector3.prototype, {
 
 	angleTo: function ( v ) {
 
+		// assumes this and v are not the zero vector
+
 		var theta = this.dot( v ) / ( Math.sqrt( this.lengthSq() * v.lengthSq() ) );
 
 		// clamp, to handle numerical problems