Improvements to Raycaster docs

docs/api/core/Raycaster.html

@@ -11,18 +11,39 @@
 
 		<div class="desc">
 		This class makes raycasting easier. Raycasting is used for picking and more.
-			
 		</div>
 
+		<h2>Example</h2>
+		<code>
+		var projector = new THREE.Projector();
+		var mouse2D = new THREE.Vector3();
 
-		<h2>Constructor</h2>
+		function onMouseMove() {
+			mouse2D.x = 2 * ( e.clientX / window.innerWidth ) - 1;
+			mouse2D.y = 1 - 2 * ( e.clientY / window.innerHeight );
+		}
+
+		window.addEventListener( 'mousemove', onMouseMove, false );
+
+		function render() {
+
+			var raycaster = projector.pickingRay( mouse2D.clone(), camera );
+			var intersects = raycaster.intersectObjects( scene.children );
 
+			for ( var intersect in intersects ) {
+				intersect.object.material.color = new THREE.Color( 0xff0000 );
+			}
+
+		}
+		</code>
+
+		<h2>Constructor</h2>
 
 		<h3>[name]( [page:Vector3 origin], [page:Vector3 direction], [page:Float near], [page:Float far] ) {</h3>
 		<div>
 		[page:Vector3 origin] — The origin vector where the ray casts from.<br />
 		[page:Vector3 direction] — The direction vector that  gives direction to the ray.<br />
-		[page:Float near] — All results returned are further away then near. Near can't be negative. Default value is 0.<br />
+		[page:Float near] — All results returned are further away than near. Near can't be negative. Default value is 0.<br />
 		[page:Float far] — All results returned are closer then far. Far can't be lower then near . Default value is Infinity.
 		</div>
 		<div>
@@ -51,7 +72,12 @@
 
 		<h3>.[page:float precision]</h3>
 		<div>
-		The precision factor of the raycaster. 
+		The precision factor of the raycaster when intersecting [page:Mesh] objects. 
+		</div>
+
+		<h3>.[page:float linePrecision]</h3>
+		<div>
+		The precision factor of the raycaster when intersecting [page:Line] objects. 
 		</div>
 
 		<h2>Methods</h2>
@@ -67,14 +93,31 @@
 
 		<h3>.intersectObject( [page:Object3D object], [page:Boolean recursive] )</h3>
 		<div>
+		<p>
 		[page:Object3D object] — The object to check for intersection with the ray.<br />
 		[page:Boolean recursive] — If set, it also checks all descendants. Otherwise it only checks intersecton with the object.
+		</p>
+
+		<p>
+		*Raycaster* delegates to the [page:Object3D.raycast raycast] method of the passed object, when evaluating whether the ray intersects the object or not. This allows [page:Mesh meshes] to respond differently than [page:Line lines] to ray casting.
+		</p>
 		</div>
 		<div>
 		checks all intersection between the ray and the object with or without the descendants. Intersections are returned sorted by distance, closest first.
         <code>
-            [ { distance, point, face, faceIndex, object }, ... ]
+            [ { distance, point, face, faceIndex, indices, object }, ... ]
         </code>
+        <p>
+        [page:Float distance] – distance between the origin of the ray and the intersection<br />
+        [page:Vector3 point] – point of intersection, in world coordinates<br />
+        [page:Face3 face] – intersected face<br />
+        [page:Integer faceIndex] – index of the intersected face<br />
+        [page:Array indices] – indices of vertices comprising the intersected face<br />
+        [page:Object3D object] – the intersected object
+    	</p>
+        <p>
+        Note that when intersecting a [page:Mesh] with a [page:BufferGeometry], the *face* and *faceIndex* will be *undefined*, and *indices* will be set; when intersecting a [page:Mesh] with a [page:Geometry], *indices* will be *undefined*. 
+        </p>
 		</div>
 
 		<h3>.intersectObjects( [page:Array objects], [page:Boolean recursive] )</h3>
@@ -83,10 +126,7 @@
 		[page:Boolean recursive] — If set, it also checks all descendants of the objects. Otherwise it only checks intersecton with the objects.
 		</div>
 		<div>
-		checks all intersection between the ray and the objects with or without the descendants. Intersections are returned sorted by distance, closest first.
-        <code>
-            [ { distance, point, face, faceIndex, object }, ... ]
-        </code>
+		checks all intersection between the ray and the objects with or without the descendants. Intersections are returned sorted by distance, closest first. Intersections are of the same form as those returned by [page:.intersectObject].
 		</div>