Updated Color doc

docs/api/math/Color.html

@@ -11,51 +11,77 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		Represents a color.
+		Class representing a color.
 		</div>
 
 
-		<h2>Example</h2>
-		<code>var color = new THREE.Color();</code>
-		<code>var color = new THREE.Color( 0xff0000 );</code>
-		<code>var color = new THREE.Color("rgb(255, 0, 0)");</code>
-		<code>var color = new THREE.Color("rgb(100%, 0%, 0%)");</code>
-		<code>var color = new THREE.Color("hsl(0, 100%, 50%)");</code>
-		<code>var color = new THREE.Color( 1, 0, 0 );</code>
+		<h2>Examples</h2>
+		A Color can be initialised in any of the following ways:
+		<code>
+//empty constructor - will default white
+var color = new THREE.Color();
+
+//Hexadecimal color (recommended)
+var color = new THREE.Color( 0xff0000 );
+
+//RGB string
+var color = new THREE.Color("rgb(255, 0, 0)");
+var color = new THREE.Color("rgb(100%, 0%, 0%)");
+
+//X11 color name - all 140 color names are supported.
+//Note the lack of CamelCase in the name
+var color = new THREE.Color( 'skyblue' );
+
+//HSL string
+var color = new THREE.Color("hsl(0, 100%, 50%)");
+
+//Seperate RGB values between 0 and 1
+var color = new THREE.Color( 1, 0, 0 );
+		</code>
+
 
 
 		<h2>Constructor</h2>
 
 
-		<h3>[name]( r, g, b )</h3>
+		<h3>[name]( [page:Multi r], [page:Float g], [page:Float b] )</h3>
 		<div>
-		r - the red component of the color if arguments g and b are defined. If they are not defined, it can be a hexadecimal or a CSS-style string or a Color instance.<br />
-		g - The green component of the color if it is defined.<br />
-		b - The blue component of the color if it is defined. 
-		</div>
-		<div>
-		All arguments are optional. The default color is White.<br />
+		[page:Multi r] - (optional) the red component of the color if arguments g and b are defined.
+		If they are not defined, it can be a [link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet] (recommended) or a CSS-style string or another Color instance.<br />
+		[page:Float g] - (optional) The green component of the color if it is defined.<br />
+		[page:Float b] - (optional) The blue component of the color if it is defined.<br /><br />
+
+		Note that standard method of specifying color in Three is with a [link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet], and that method is used
+		throughout the rest of the documentation.<br /><br />
+
 		When all arguments are defined then r is the red component, g is the green component and b is the blue component of the color.<br />
 		When only r is defined:<br />
 		<ul>
-			<li>It can be a hexadecimal of the color.</li>
-			<li>It can be an another color instance.</li>
-			<li>It can be a CSS style. For Instance:
+			<li>It can be a [link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet] representing the color (recommended).</li>
+			<li>It can be an another Color instance.</li>
+			<li>It can be a CSS style string. For Instance:
 				<ul>
-					<li>rgb(250, 0,0)</li>
-					<li>rgb(100%,0%,0%)</li>
-					<li>hsl(0, 100%, 50%)</li>
-					<li>#ff0000</li>
-					<li>#f00</li>
-					<li>red</li>
+					<li>'rgb(250, 0,0)'</li>
+					<li>'rgb(100%,0%,0%)'</li>
+					<li>'hsl(0, 100%, 50%)'</li>
+					<li>'#ff0000'</li>
+					<li>'#f00'</li>
+					<li>'red'</li>
 				</ul>
-			
+
 			</li>
 		</ul>
 		</div>
 
 		<h2>Properties</h2>
 
+		<h3>[property:Boolean isColor]</h3>
+		<div>
+			Used to check whether this or derived classes are Colors. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally for optimisation.
+		</div>
+
 		<h3>[property:Float r]</h3>
 		<div>
 		Red channel value between 0 and 1. Default is 1.
@@ -71,183 +97,183 @@
 		Blue channel value between 0 and 1. Default is 1.
 		</div>
 
+
+
+
+
+
 		<h2>Methods</h2>
 
-		<h3>[method:Color set]( value ) [page:Color this]</h3>
-		<div>
-		value -- either an instance of [page:Color], a [page:Integer hexadecimal] value, or a css style [page:String string]
-		</div>
-		<div>
-		Delegates to .copy, .setStyle, or .setHex depending on input type.
-		</div>
+		<h3>[method:Color add]( [page:Color color] ) </h3>
+		<div>Adds the RGB values of [page:Color color] to the RGB values of this color.</div>
 
-		<h3>[method:Color copy]( [page:Color color] ) [page:Color this]</h3>
-		<div>
-		color — Color to copy.
-		</div>
-		<div>
-		Copies given color.
-		</div>
+		<h3>[method:Color addColors]( [page:Color color1], [page:Color color2] ) </h3>
+		<div>Sets this color's RGB values to the sum of the RGB values of [page:Color color1] and [page:Color color2].</div>
 
-		<h3>[method:Color fromArray]( [page:Array array], [page:Integer offset] ) [page:Color this]</h3>
-		<div>
-		array -- [page:Array] [r, g, b] <br />
-		offset -- [page:Integer] An optional offset into the array.
-		</div>
-		<div>
-		Sets this color's components based on an array formatted like [r, g, b]
-		</div>
+		<h3>[method:Color addScalar]( [page:Number s] ) </h3>
+		<div>Adds [page:Number s] to the RGB values of this color.</div>
 
-		<h3>[method:Color copyGammaToLinear]( [page:Color color] ) [page:Color this]</h3>
-		<div>
-		color — Color to copy.
-		</div>
-		<div>
-		Copies given color making conversion from gamma to linear space.
-		</div>
+		<h3>[method:Color clone]() </h3>
+		<div>Returns a new Color with the same  [page:.r r], [page:.g g] and [page:.b b] parameters a this one.</div>
 
-		<h3>[method:Color copyLinearToGamma]( [page:Color color] ) [page:Color this]</h3>
+		<h3>[method:Color copy]( [page:Color color] ) </h3>
 		<div>
-		color — Color to copy.
-		</div>
-		<div>
-		Copies given color making conversion from linear to gamma space.
+			Copies the [page:.r r], [page:.g g] and [page:.b b] parameters from [page:Color color] in to this color.
 		</div>
 
-		<h3>[method:Color convertGammaToLinear]() [page:Color this]</h3>
-		<div>
-		Converts this color from gamma to linear space.
-		</div>
+		<h3>[method:Color convertGammaToLinear]() </h3>
+		<div>Converts this color from gamma to linear space (squares the values of [page:.r r], [page:.g g] and [page:.b b] ).</div>
+
+		<h3>[method:Color convertLinearToGamma]() </h3>
+		<div>Converts this color from linear to gamma space (takes the squareroot of [page:.r r], [page:.g g] and [page:.b b]).</div>
 
-		<h3>[method:Color convertLinearToGamma]() [page:Color this]</h3>
+		<h3>[method:Color copyGammaToLinear]( [page:Color color], [page:Float gammaFactor] ) </h3>
 		<div>
-		Converts this color from linear to gamma space.
+		[page:Color color] — Color to copy.<br />
+		[page:Float gammaFactor] - (optional). Default is *2.0*.<br /><br />
+
+		Copies given color making conversion from gamma to linear space,
+		by taking [page:.r r], [page:.g g] and [page:.b b] to the power of [page:Float gammaFactor].
 		</div>
 
-		<h3>[method:Color setRGB]( [page:Float r], [page:Float g], [page:Float b] ) [page:Color this]</h3>
+		<h3>[method:Color copyLinearToGamma]( [page:Color color], [page:Float gammaFactor] ) </h3>
 		<div>
-		r — Red channel value between 0 and 1.<br />
-		g — Green channel value between 0 and 1.<br />
-		b — Blue channel value between 0 and 1.
+		[page:Color color] — Color to copy.<br />
+		[page:Float gammaFactor] - (optional). Default is *2.0*.<br /><br />
+
+		Copies given color making conversion from linear to gamma space,
+		by taking [page:.r r], [page:.g g] and [page:.b b] to the power of 1 / [page:Float gammaFactor].
 		</div>
+
+		<h3>[method:Boolean equals]( [page:Color color] ) </h3>
+		<div>Compares [page:Color color] with this one and returns true if they are the same, false otherwise.</div>
+
+		<h3>[method:Color fromArray]( [page:Array array], [page:Integer offset] ) </h3>
 		<div>
-		Sets this color from RGB values.
+		[page:Array array] - [page:Array] of float in the form [ [page:Float r], [page:Float g], [page:Float b] ].<br />
+		[page:Integer offset] - An optional offset into the array.<br /><br />
+
+		Sets this color's components based on an array formatted like [ [page:Float r], [page:Float g], [page:Float b] ].
 		</div>
 
 		<h3>[method:Integer getHex]()</h3>
-		<div>
-		Returns the hexadecimal value of this color.
-		</div>
+		<div>Returns the hexadecimal value of this color.</div>
 
 		<h3>[method:String getHexString]()</h3>
-		<div>
-		Returns the string formated hexadecimal value of this color.
-		</div>
+		<div>Returns the string formatted hexadecimal value of this color.</div>
 
-		<h3>[method:Color setHex]( [page:Integer hex] ) [page:Color this]</h3>
-		<div>
-		hex — Color in hexadecimal.<br />
-		</div>
+		<h3>[method:Object getHSL]( [page:Object optionalTarget] )</h3>
 		<div>
-		Sets this color from a hexadecimal value.
-		</div>
+			[page:Object optionalTarget] - (optional) object into which to pass the results.<br /><br />
 
-		<h3>[method:Color setStyle]( [page:String style] ) [page:Color this]</h3>
-		<div>
-		style — color as a CSS-style string.
-		</div>
-		<div>
-		Sets this color from a CSS-style string. For example, "rgb(250, 0,0)", "rgb(100%, 0%, 0%)", "hsl(0, 100%, 50%)", "#ff0000", "#f00", or "red". Transluent colors such as "rgba(255, 0, 0, 0.5)" and "hsla(0, 100%, 50%, 0.5)" are also accepted, but the alpha-channel coordinate will be discarded.
+			Convert the values [page:.r r], [page:.g g] and [page:.b b] to [link:https://en.wikipedia.org/wiki/HSL_and_HSV HSL]
+			format and returns an object of the form:
+
+			<code>
+				{ h: 0, s: 0, l: 0 }
+			</code>
+
+			If [page:Object optionalTarget] is passed in, adds h, s and l keys to that object (if not already present)
+			and sets the results there.
 		</div>
 
 		<h3>[method:String getStyle]()</h3>
-		<div>
-		Returns the value of this color as a CSS-style string. Example: rgb(255,0,0)
-		</div>
+		<div>Returns the value of this color as a CSS-style string. Example: 'rgb(255,0,0)'.</div>
 
-		<h3>[method:Color setScalar]( [page:Float scalar] ) [page:Color this]</h3>
-		<div>
-		scalar — a value between 0.0 and 1.0.
-		</div>
+		<h3>[method:Color lerp]( [page:Color color], [page:Float alpha] ) </h3>
 		<div>
-		Sets all three color components to the value *scalar*.
-		</div>
+		[page:Color color] - color to converge on.<br />
+		[page:Float alpha] - a number between 0 and 1.<br /><br />
 
-		<h3>[method:Color setHSL]( [page:Float h], [page:Float s], [page:Float l] ) [page:Color this]</h3>
-		<div>
-		h — hue value between 0.0 and 1.0 <br />
-		s — saturation value between 0.0 and 1.0 <br />
-		l — lightness value between 0.0 and 1.0
-		</div>
-		<div>
-		Sets color from hsl
+		Linear interpolation of this colors RGB values and the RGB values of the passed argument.
+		The alpha argument can be thought of as the percent between the two colors, where 0 is
+		this color and 1 is the first argument.
 		</div>
 
-		<h3>[method:Object getHSL]() [page:Object hsl]</h3>
-		<div>
-		Returns an object with properties h, s, and l.
-		</div>
+		<h3>[method:Color multiply]( [page:Color color] ) </h3>
+		<div>Multiplies this color's RGB values by given [page:Color color]'s RGB values.</div>
 
-		<h3>[method:Color offsetHSL]( [page:Float h], [page:Float s], [page:Float l] ) [page:Color this]</h3>
-		<div>
-		Adds given h, s, and l to this color's existing h, s, and l values.
-		</div>
+		<h3>[method:Color multiplyScalar]( [page:Number s] ) </h3>
+		<div>Multiplies this color's RGB values by [page:Number s].</div>
 
-		<h3>[method:Color sub]( [page:Color color] ) [page:Color this]</h3>
+		<h3>[method:Color offsetHSL]( [page:Float h], [page:Float s], [page:Float l] ) </h3>
 		<div>
-		Subtracts rgb components of given color from rgb components of this color. If a component is negative, it is set to zero.
+			Adds given [page:Float h], [page:Float s], and [page:Float l] to this color's existing values.
+			Internally this converts the [page:.r r], [page:.g g] and [page:.b b] values to HSL, adds
+			[page:Float h], [page:Float s], and [page:Float l] and then converts back to RGB.
 		</div>
 
-		<h3>[method:Color add]( [page:Color color] ) [page:Color this]</h3>
+		<h3>[method:Color set]( [page:Multi value] ) </h3>
 		<div>
-		Adds rgb values of given color to rgb values of this color
-		</div>
+		[page:Multi value] - Value to set this color to.<br /><br />
 
-		<h3>[method:Color addColors]( [page:Color color1], [page:Color color2] ) [page:Color this]</h3>
-		<div>
-		Sets this color to the sum of color1 and color2
+		See the Constructor above for full details of what [page:Multi value] can be.
+		Delegates to [page:.copy], .setStyle, or .setHex depending on input type.
 		</div>
 
-		<h3>[method:Color addScalar]( [page:Number s] ) [page:Color this]</h3>
+		<h3>[method:Color setHex]( [page:Integer hex] ) </h3>
 		<div>
-		Adds s to the rgb values of this color
-		</div>
+		[page:Integer hex] — [link:https://en.wikipedia.org/wiki/Web_colors#Hex_triplet hexadecimal triplet] format.<br /><br />
 
-		<h3>[method:Color multiply]( [page:Color color] ) [page:Color this]</h3>
-		<div>
-		Multiplies this color's rgb values by given color's rgb values
+		Sets this color from a hexadecimal value.
 		</div>
 
-		<h3>[method:Color multiplyScalar]( [page:Number s] ) [page:Color this]</h3>
+		<h3>[method:Color setHSL]( [page:Float h], [page:Float s], [page:Float l] ) </h3>
 		<div>
-		Multiplies this color's rgb values by s
-		</div>
+		[page:Float h] — hue value between 0.0 and 1.0 <br />
+		[page:Float s] — saturation value between 0.0 and 1.0 <br />
+		[page:Float l] — lightness value between 0.0 and 1.0<br /><br />
 
-		<h3>[method:Color lerp]( [page:Color color], alpha ) [page:Color this]</h3>
-		<div>
-		alpha -- a number between 0 and 1.
+		Sets color from HSL values.
 		</div>
+
+		<h3>[method:Color setRGB]( [page:Float r], [page:Float g], [page:Float b] ) </h3>
 		<div>
-		Linear interpolation of this colors rgb values and the rgb values of the first argument. The alpha argument can be thought of as the percent between the two colors, where 0 is this color and 1 is the first argument.
+		[page:Float r] — Red channel value between 0 and 1.<br />
+		[page:Float g] — Green channel value between 0 and 1.<br />
+		[page:Float b] — Blue channel value between 0 and 1.<br /><br />
+
+		Sets this color from RGB values.
 		</div>
 
-		<h3>[method:Boolean equals]( [page:Color c] ) [page:Color this]</h3>
+		<h3>[method:Color setScalar]( [page:Float scalar] ) </h3>
 		<div>
-		Compares this color and c and returns true if they are the same, false otherwise.
+		[page:Float scalar] — a value between 0.0 and 1.0.<br /><br />
+
+		Sets all three color components to the value [page:Float scalar].
 		</div>
 
-		<h3>[method:Color clone]() [page:Color this]</h3>
+		<h3>[method:Color setStyle]( [page:String style] ) </h3>
 		<div>
-		Clones this color.
+		[page:String style] — color as a CSS-style string.<br /><br />
+
+		Sets this color from a CSS-style string. For example,
+		"rgb(250, 0,0)",
+		"rgb(100%, 0%, 0%)",
+		"hsl(0, 100%, 50%)",
+		"#ff0000",
+		"#f00", or
+		"red" ( or any [link:https://en.wikipedia.org/wiki/X11_color_names#Color_name_chart X11 color name]
+		- all 140 color names are supported ).<br />
+
+		Transluent colors such as "rgba(255, 0, 0, 0.5)" and "hsla(0, 100%, 50%, 0.5)" are also accepted,
+		but the alpha-channel coordinate will be discarded.<br /><br />
+
+		Note that for X11 color names, multiple words such as Dark Orange become the string 'darkorange' (all lowercase).
 		</div>
 
-		<h3>[method:Array toArray]( [page:Array array], [page:Integer offset] ) [page:Color this]</h3>
+		<h3>[method:Color sub]( [page:Color color] ) </h3>
 		<div>
-		array -- An optional array to store the color to. <br />
-		offset -- An optional offset into the array.
+		Subtracts RGB components of the given color from the RGB components of this color.
+		If a component is negative, it is set to zero.
 		</div>
+
+		<h3>[method:Array toArray]( [page:Array array], [page:Integer offset] ) </h3>
 		<div>
-		Returns an array [r,g,b]
+		[page:Array array] - An optional array to store the color to. <br />
+		[page:Integer offset] - An optional offset into the array.<br /><br />
+
+		Returns an array of the form [ r, g, b ].
 		</div>
 
 		<h2>Source</h2>