Updated DirectionalLight doc

docs/api/lights/AmbientLight.html

@@ -13,8 +13,9 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-			This light globally illuminates all objects in the scene equally. It does not have a direction
-			so can't be used to cast shadows. 
+			This light globally illuminates all objects in the scene equally.<br /><br />
+
+			This light cannot be used to cast shadows as it does not have a direction. 
 		</div>
 
 

docs/api/lights/DirectionalLight.html

@@ -13,70 +13,126 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-			Affects objects using [page:MeshLambertMaterial] or [page:MeshPhongMaterial].
+			A light that gets emitted in a specific direction. This light will behave	as though it is
+			infinitely far away and the rays produced from it are all parallel. The common use case
+			for this is to simulate daylight; the sun is far enough away that its position can be
+			considered to be infinite, and all light rays coming from it are parallel.<br /><br />
+
+			This light can cast shadows - see the [page:DirectionalLightShadow] page for details.
+		</div>
+
+		<h2>A Note about Position, Target and rotation</h2>
+		<div>
+			A common point of confusion for directional lights is that setting the rotation has no effect.
+			This is because Three's DirectionalLight is the equivalent to what is often called a 'Target
+			Direct Light' in other applications.<br /><br />
+
+			This means that its direction is calculated as pointing
+			from the light's [page:Object3D.position position] to	the [page:.target target]'s position
+			(as opposed to a a 'Free Direct Light' that just has a rotation component).<br /><br />
+
+			The reason for this is to allow the light to cast shadows - the [page:.shadow shadow]
+			camera needs a position to calculate shadows from.<br /><br />
+
+			See the [page:.target target] property below for details on updating the target.
 		</div>
 
 
 		<h2>Example</h2>
-		<div>[example:canvas_morphtargets_horse morphtargets / horse ]</div>
-		<div>[example:misc_controls_fly controls / fly ]</div>
-		<div>[example:misc_lights_test lights / test ]</div>
-		<div>[example:vr_cubes cubes ]</div>
-		<div>[example:webgl_effects_parallaxbarrier effects / parallaxbarrier ]</div>
-		<div>[example:webgl_effects_stereo effects / stereo ]</div>
-		<div>[example:webgl_geometry_extrude_splines geometry / extrude / splines ]</div>
-		<div>[example:webgl_materials_bumpmap materials / bumpmap ]</div>
-		<div>[example:webgl_materials_cubemap_balls_reflection materials / cubemap / balls / reflection ]</div>
-
-		<code>// White directional light at half intensity shining from the top.
+		<div>
+			[example:canvas_morphtargets_horse morphtargets / horse ]<br />
+			[example:misc_controls_fly controls / fly ]<br />
+			[example:misc_lights_test lights / test ]<br />
+			[example:vr_cubes cubes ]<br />
+			[example:webgl_effects_parallaxbarrier effects / parallaxbarrier ]<br />
+			[example:webgl_effects_stereo effects / stereo ]<br />
+			[example:webgl_geometry_extrude_splines geometry / extrude / splines ]<br />
+			[example:webgl_materials_bumpmap materials / bumpmap ]<br />
+			[example:webgl_materials_cubemap_balls_reflection materials / cubemap / balls / reflection ]
+		</div>
 
+		<code>
+// White directional light at half intensity shining from the top.
 var directionalLight = new THREE.DirectionalLight( 0xffffff, 0.5 );
 directionalLight.position.set( 0, 1, 0 );
-scene.add( directionalLight );</code>
+scene.add( directionalLight );
+	</code>
 
 
 		<h2>Constructor</h2>
 
 		<h3>[name]( [page:Integer hex], [page:Float intensity] )</h3>
 		<div>
-		[page:Integer hex] -- Numeric value of the RGB component of the color. <br />
-		[page:Float intensity] -- Numeric value of the light's strength/intensity.
-		</div>
-		<div>
-		Creates a light that shines from a specific direction not from a specific position.  This light will behave
-		as though it is infinitely far away and the rays produced from it are all parallel.  The best
-		analogy would be a light source that acts like the sun: the sun is so far away that all sunlight
-		hitting objects comes from the same angle.
+			[page:Integer color] - (optional) hexadecimal color of the light. Default is 0xffffff (white).<br />
+			[page:Float intensity] - (optional) numeric value of the light's strength/intensity. Default is 1.<br /><br />
+
+			Creates a new [name].
 		</div>
 
 		<h2>Properties</h2>
 
 		See the base [page:Light Light] class for common properties.
 
-		<h3>[property:Object3D target]</h3>
+		<h3>[property:Boolean castShadow]</h3>
 		<div>
-			Target used for shadow camera orientation.
+			If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and
+			requires tweaking to get shadows looking right. See the [page:DirectionalLightShadow] for details.
+			The default is *false*.
+		</div>
+
+		<h3>[property:Boolean isDirectionalLight]</h3>
+		<div>
+			Used to check whether this or derived classes are dircrectional lights. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
+		</div>
+
+
+		<h3>[property:Vector3 position]</h3>
+		<div>
+			This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
 		</div>
 
 		<h3>[property:DirectionalLightShadow shadow]</h3>
 		<div>
-			This property stores all relevant information for rendering the shadow of the light.<br />
+			A [page:DirectionalLightShadow] used to calculate shadows for this light.
 		</div>
 
-		<h3>[property:Boolean castShadow]</h3>
+		<h3>[property:Object3D target]</h3>
 		<div>
-			If set to *true* light will cast dynamic shadows. *Warning*: This is expensive and requires tweaking to get shadows looking right.<br />
-			Default — *false*.
+			The DirectionalLight points from its [page:.position position] to target.position. The default
+			position of the target is *(0, 0, 0)*.<br />
+
+			*Note*: For the the target's position to be changed to anything other than the default,
+			it must be added to the [page:Scene scene] using
+			<code>
+				scene.add( light.target );
+			</code>
+
+			This is so that the target's [page:Object3D.matrixWorld matrixWorld] gets automatically
+			updated each frame.<br /><br />
+
+			It is also possible to set the target to be another object in the scene (anything with a
+			[page:Object3D.position position] property), like so:
+			<code>
+	var targetObject = new THREE.Object3D();
+	scene.add(targetObject);
+
+	light.target = targetObject;
+			</code>
+			The directionalLight will now track the target object.
 		</div>
 
+
+
 		<h2>Methods</h2>
 
 		See the base [page:Light Light] class for common methods.
 
 		<h3>[method:DirectionalLight copy]( [page:DirectionalLight source] )</h3>
 		<div>
-		<br />
-		Copies value of *source* to this DirectionalLight object.
+		Copies value of all the properties from the [page:DirectionalLight source] to this
+		DirectionalLight.
 		</div>
 
 		<h2>Source</h2>

docs/api/lights/HemisphereLight.html

@@ -13,7 +13,9 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-			A light source positioned directly above the scene, with color fading from the sky color to the ground color.
+			A light source positioned directly above the scene, with color fading from the
+			sky color to the ground color. <br /><br />
+
 			This light cannot be used to cast shadows.
 		</div>
 
@@ -75,7 +77,7 @@ scene.add( light );
 
 		<h3>[property:Vector3 position]</h3>
 		<div>
-			This is set equal to [page:Object3D.DefaultUp], so that the light shines from the top down.
+			This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
 		</div>
 
 

docs/api/lights/PointLight.html

@@ -14,7 +14,9 @@
 
 		<div class="desc">
 			A light that gets emitted from a single point in all directions. A common use case for this
-			is to replicate the light emitted from a bare lightbulb. This light can cast shadows (see [page:LightShadow]).
+			is to replicate the light emitted from a bare lightbulb.<br /><br />
+
+			 This light can cast shadows - see [page:LightShadow] page for details.
 		</div>
 
 

docs/api/lights/SpotLight.html

@@ -14,7 +14,9 @@
 
 		<div class="desc">
 			This light gets emitted from a single point in one direction, along a cone that increases in size
-			the further from the light it gets. This light can cast shadows - see the [page:SpotLightShadow].
+			the further from the light it gets. <br /><br />
+
+			This light can cast shadows - see the [page:SpotLightShadow] page for details.
 		</div>
 
 
@@ -30,7 +32,6 @@
 		<h2>Other Examples</h2>
 
 		<div>
-
 			[example:webgl_interactive_cubes_gpu interactive / cubes / gpu ]<br />
 			[example:webgl_interactive_draggablecubes interactive / draggablecubes ]<br />
 			[example:webgl_materials_bumpmap_skin materials / bumpmap / skin ]<br />
@@ -125,6 +126,11 @@
 			zero and 1. The default is *0.0*.
 		</div>
 
+		<h3>[property:Vector3 position]</h3>
+		<div>
+			This is set equal to [page:Object3D.DefaultUp] (0, 1, 0), so that the light shines from the top down.
+		</div>
+
 		<h3>[property:Float power]</h3>
 		<div>
 			The light's power.<br />
@@ -140,7 +146,7 @@
 
 		<h3>[property:SpotLightShadow shadow]</h3>
 		<div>
-			A [page:LightShadow] used to calculate shadows for this light.
+			A [page:SpotLightShadow] used to calculate shadows for this light.
 		</div>