Merge pull request #10138 from looeee/docs/extras/core/improve

Improved docs for extras / core

docs/api/extras/core/Curve.html

@@ -30,35 +30,57 @@
 
 		<h2>Methods</h2>
 
-		<h3>[method:Vector getPoint]( t )</h3>
+		<h3>[method:Vector getPoint]( [page:Number t] )</h3>
 		<div>Returns a vector for point t of the curve where t is between 0 and 1. Must be implemented in the extending class.</div>
 
-		<h3>[method:Vector getPointAt]( u )</h3>
-		<div>Returns a vector for point at relative position in curve according to arc length</div>
+		<h3>[method:Vector getPointAt]( [page:Number u] )</h3>
+		<div>
+			Returns a vector for point at a relative position in curve according to arc length.
+			u is in the range [0, 1].
+		</div>
 
-		<h3>[method:Array getPoints]( divisions )</h3>
-		<div>Get sequence of points using getPoint( t ) </div>
+		<h3>[method:Array getPoints]( [page:integer divisions] )</h3>
+		<div>
+			divisions -- number of pieces to divide the curve into. Default is *5*.<br /><br />
+
+			Returns a set of divisions + 1 points using getPoint( t ).
+		</div>
 
 		<h3>[method:Array getSpacedPoints]( divisions )</h3>
-		<div>Get sequence of equi-spaced points using getPointAt( u )</div>
+		<div>
+			divisions -- number of pieces to divide the curve into. Default is *5*.<br /><br />
+
+			Returns a set of divisions + 1 equi-spaced points using getPointAt( u ).
+		</div>
 
 		<h3>[method:Float getLength]()</h3>
-		<div>Get total curve arc length</div>
+		<div>Get total curve arc length.</div>
 
 		<h3>[method:Array getLengths]( divisions )</h3>
-		<div>Get list of cumulative segment lengths</div>
+		<div>Get list of cumulative segment lengths.</div>
 
 		<h3>[method:null updateArcLengths]()</h3>
-		<div>Update the cumlative segment distance cache</div>
+		<div>Update the cumlative segment distance cache.</div>
 
-		<h3>[method:Float getUtoTmapping]( u, distance )</h3>
-		<div>Given u ( 0 .. 1 ), get a t to find p. This gives you points which are equidistant</div>
+		<h3>[method:Float getUtoTmapping]( [page:Number u], distance )</h3>
+		<div>
+			Given u in the range ( 0 .. 1 ), returns [page:Number t] also in the range ( 0 .. 1 ).
+			u and t can then be used to give you points which are equidistant from the ends of the curve,
+			using [page:.getPoint].
+		 </div>
 
-		<h3>[method:Vector getTangent]( t )</h3>
-		<div>Returns a unit vector tangent at t. If the subclassed curve do not implement its tangent derivation, 2 points a small delta apart will be used to find its gradient which seems to give a reasonable approximation</div>
+		<h3>[method:Vector getTangent]( [page:Number t] )</h3>
+		<div>
+			Returns a unit vector tangent at t. If the subclassed curve do not implement its
+			tangent derivation, 2 points a small delta apart will be used to find its gradient
+			which seems to give a reasonable approximation
+		</div>
 
-		<h3>[method:Vector getTangentAt]( u )</h3>
-		<div>Returns tangent at equidistant point u on the curve</div>
+		<h3>[method:Vector getTangentAt]( [page:Number u] )</h3>
+		<div>
+			Returns tangent at a point which is equidistant to the ends of the curve from the
+			point given in [page:.getTangent].
+		</div>
 
 		<h3>[method:Object computeFrenetFrames]( segments, closed )</h3>
 		<div>

docs/api/extras/core/CurvePath.html

@@ -13,7 +13,7 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		An abstract base class further extending [page:Curve]. A CurvePath is simply an array of connected curves,
+		An abstract base class extending [page:Curve]. A CurvePath is simply an array of connected curves,
 		but retains the api of a curve.
 		</div>
 
@@ -28,112 +28,53 @@
 
 
 		<h2>Properties</h2>
-
+		<div>See the base [page:Curve] class for common properties.</div>
 
 		<h3>[property:array curves]</h3>
-		<div>
-		The array of [page:Curve]s
-		</div>
-
-		<h3>[property:array bends]</h3>
-		<div>
-		An array of [page:Curve]s used to transform and bend the curve using [page:CurvePath.getWrapPoints].
-		</div>
+		<div>The array of [page:Curve Curves].</div>
 
 		<h3>[property:boolean autoClose]</h3>
-		<div>
-		Whether or not to automatically close the path.
-		</div>
+		<div>Whether or not to automatically close the path.</div>
 
-		<h2>Methods</h2>
 
 
-		<h3>[method:Array getWrapPoints]( [page:Array vertices], [page:Curve curve] )</h3>
-		<div>
-		vertices -- An array of [page:Vector2]s to modify<br />
-		curve -- An array of 2d [page:Curve]s
-		</div>
-		<div>
-		Modifies the array of vertices by warping it by the curve. The curve parameter also accepts objects with similar
-		interfaces such as [page:CurvePath], [page:Path], [page:SplineCurve], etc. Returns the original vertices after
-		modification.
-		</div>
 
-		<h3>[method:null addWrapPath]( [page:Curve curve] )</h3>
-		<div>
-		curve -- A [page:Curve] or object with a similar interface.
-		</div>
-		<div>
-		Pushes a curve onto the bends array.
-		</div>
+
+		<h2>Methods</h2>
+		<div>See the base [page:Curve] class for common methods.</div>
+
+		<h3>[method:null add]( [page:Curve curve] )</h3>
+		<div>Add a curve to the [page:.curves] array.</div>
+
+		<h3>[method:null closePath]()</h3>
+		<div>Adds a [page:LineCurve lineCurve] to close the path.</div>
 
 		<h3>[method:Geometry createGeometry]( [page:Vector3 points] )</h3>
 		<div>
-		points -- An array of [page:Vector3]s
-		</div>
-		<div>
+		points -- An array of [page:Vector3 Vector3s]<br /><br />
+
 		Creates a geometry from points
 		</div>
 
 		<h3>[method:Geometry createPointsGeometry]( [page:Integer divisions] )</h3>
 		<div>
-		divisions -- How many segments to create with [page:Vector3]s. Defaults to 12.
-		</div>
-		<div>
-		Creates a [page:Geometry] object comprised of [page:Vector3]s
-		</div>
+		divisions -- How many segments to create. Defaults to *12*.<br /><br />
 
-		<h3>[method:Geometry createSpacedPointsGeometry]( [page:Integer divisions] )</h3>
-		<div>
-		divisions -- How many segments to create with [page:Vector3]s. Defaults to 12.
+		Creates a [page:Geometry] object comprised of [page:Vector3 Vector3s], for example
+		to be used with [page:Line] or [page:Points]. Uses [page:Curve.getPoints]() for the division.
 		</div>
-		<div>
-		Creates a [page:Geometry] object comprised of [page:Vector3]s that are equidistant.
-		</div>
-
 
-		<h3>[method:null add]( [page:Curve curve] )</h3>
-		<div>
-		curve -- The [page:Curve curve] to add
-		</div>
+		<h3>[method:Geometry createSpacedPointsGeometry]( [page:Integer divisions] )</h3>
 		<div>
-		Pushes a curve onto the curves array.
-		</div>
+		divisions -- How many segments to create. Defaults to *12*.<br /><br />
 
-		<h3>[method:null closePath]()</h3>
-		<div>
-		Adds a curve to close the path.
-		</div>
-
-		<h3>[method:Object getBoundingBox]()</h3>
-		<div>
-		Returns an object with the keys minX, minY, maxX, maxY, (if 3d: maxZ, minZ)
+		Creates a [page:Geometry] object comprised of [page:Vector3]s that are equidistant, for example
+		to be used with [page:Line] or [page:Points].	Uses [page:Curve.getSpacedPoints]() for the division.
 		</div>
 
 		<h3>[method:Float getCurveLengths]()</h3>
-		<div>
-		Adds together the length of the curves
-		</div>
+		<div>Adds together the lengths of the curves in the [page:.curves] array.</div>
 
-		<h3>[method:Array getTransformedPoints]( [page:Integer segments], [page:Array bends] )</h3>
-		<div>
-		segments -- The number of segments to create using the getPoints()<br />
-		bends -- (optional) An array of [page:Curve]s used to transform the points. Defaults to this.bends if blank.
-		</div>
-		<div>
-		Uses this CurvePath to generate a series of points transformed by the curves in the bends array. Returns an
-		array of [page:Vector2]s.
-		</div>
-
-		<h3>[method:Array getTransformedSpacedPoints]( [page:Integer segments], [page:Array bends] )</h3>
-		<div>
-		segments -- The number of segments to create using the getPoints()<br />
-		bends -- (optional) Defaults to this.bends if blank. An array of [page:Curve]s used to transform the points.
-		</div>
-		<div>
-		Uses this CurvePath to generate a series equidistant points that are then transformed by the curves in the bends.
-	    Returns an array of [page:Vector2]s.
-		</div>
 
 		<h2>Source</h2>
 

docs/api/extras/core/Font.html

@@ -11,9 +11,9 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		Create a set of [page:Shape Shape]s representing a font loaded in JSON format.<br /><br />
+		Create a set of [page:Shape Shapes] representing a font loaded in JSON format.<br /><br />
 
-		Used internally by the [page:FontLoader].
+		This is used internally by the [page:FontLoader].
 		</div>
 
 		<h2>Constructor</h2>
@@ -22,7 +22,30 @@
 		<div>
 		data -- JSON data representing the font.<br /><br />
 
-		This constructor creates a new [name], which is an array of [page:Shape Shape]s.
+		This constructor creates a new [name], which is an array of [page:Shape Shapes].
+		</div>
+
+		<h2>Properties</h2>
+
+		<h3>[property:array data]</h3>
+		<div>The JSON data passed in the constructor.</div>
+
+		<h3>[property:Boolean isFont]</h3>
+		<div>
+			Used to check whether this or derived classes are fonts. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally by the renderer for optimisation.
+		</div>
+
+		<h2>Methods</h2>
+
+		<h3>[method:null generateShapes]( [page:String text], [page:Float size], [page:Integer divisions] )</h3>
+		<div>
+			[page:String text] -- string of text.<br />
+			[page:Float size] -- (optional) scale for the [page:Shape Shapes]. Default is *100*.<br />
+			[page:Integer divisions] -- (optional) fineness of the [page:Shape Shapes]. Default is *5*.<br />
+
+			Creates an array of [page:Shape Shapes] representing the text in the font.
 		</div>
 
 		<h2>Source</h2>

docs/api/extras/core/Path.html

@@ -13,111 +13,126 @@
 		<h1>[name]</h1>
 
 		<div class="desc">
-		A 2d path representation, comprising of points, lines, and cubes, similar to the html5 2d canvas api.
+		A 2d path representation, comprising of points, lines, and cubes, similar to the 2D Canvas API.
 		It extends [page:CurvePath].
 		</div>
 
+		<h2>Example</h2>
+
+		<code>
+var v1 = new THREE.Vector3();
+var v2 = new THREE.Vector3(1, 45, 6);
+var v3 = new THREE.Vector3(34, 34, 676);
+
+var vectors = [v1, v2, v3];
+
+var path = new THREE.Path(vectors);
+		</code>
+
 
 		<h2>Constructor</h2>
 
 
 		<h3>[name]( [page:Array points] )</h3>
 		<div>
-		points -- array of Vector2
-		</div>
-		<div>
-		Creates a Path from the points. The first vector defines the offset. After that the lines get defined.
+		points -- (optional) array of [page:Vector2 Vector2s].<br /><br />
+
+		Creates a Path from the points. The first point defines the offset, then successive points
+		are added to the [page:CurvePath.curves curves] array as [page:LineCurve LineCurves].<br /><br />
+
+		If no points are specified, an empty path is created and the [page:.currentPoint] is set to
+		the origin.
 		</div>
 
 
 		<h2>Properties</h2>
+		<div>See the base [page:CurvePath] class for common properties.</div>
 
+		<h3>[property:array currentPoint]</h3>
+		<div>The current offset of the path. Any new [page:Curve] added will start here.</div>
 
-		<h3>[property:array actions]</h3>
-		<div>
-		The possible actions that define the path.
-		</div>
 
 		<h2>Methods</h2>
+		<div>See the base [page:CurvePath] class for common methods.</div>
 
-		<h3>[method:null fromPoints]( [page:Array vector2s] )</h3>
+		<h3>[method:null absarc]( [page:Float x], [page:Float y], [page:Float radius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise] )</h3>
 		<div>
-		Adds to the Path from the points. The first vector defines the offset. After that the lines get defined.
+			x, y -- The absolute center of the arc.<br />
+			radius -- The radius of the arc.<br />
+			startAngle -- The start angle in radians.<br />
+			endAngle -- The end angle in radians.<br />
+			clockwise -- Sweep the arc clockwise. Defaults to *false*.<br /><br />
+
+			Adds an absolutely positioned [page:EllipseCurve EllipseCurve] to the path.
 		</div>
 
-		<h3>[method:null moveTo]( [page:Float x], [page:Float y] )</h3>
-		<div>This moves the offset to x and y</div>
+		<h3>[method:null absellipse]( [page:Float x], [page:Float y], [page:Float xRadius], [page:Float yRadius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise], [page:Float rotation] )</h3>
+		<div>
+			x, y -- The absolute center of the ellipse.<br />
+			xRadius -- The radius of the ellipse in the x axis.<br />
+			yRadius -- The radius of the ellipse in the y axis.<br />
+			startAngle -- The start angle in radians.<br />
+			endAngle -- The end angle in radians.<br />
+			clockwise -- Sweep the ellipse clockwise. Defaults to false.<br />
+			rotation -- The rotation angle of the ellipse in radians, counterclockwise from the positive X axis. Optional, defaults to 0.<br /><br />
+
+			Adds an absolutely positioned [page:EllipseCurve EllipseCurve] to the path.
+		</div>
 
-		<h3>[method:null lineTo]( [page:Float x], [page:Float y] )</h3>
-		<div>This creates a line from the offset to X and Y and updates the offset to X and Y.</div>
+		<h3>[method:null arc]( [page:Float x], [page:Float y], [page:Float radius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise] )</h3>
+		<div>
+		x, y -- The center of the arc offset from the last call.<br />
+		radius -- The radius of the arc.<br />
+		startAngle -- The start angle in radians.<br />
+		endAngle -- The end angle in radians.<br />
+		clockwise -- Sweep the arc clockwise. Defaults to *false*.<br /><br />
 
-		<h3>[method:null quadraticCurveTo]( [page:Float cpX], [page:Float cpY], [page:Float x], [page:Float y] )</h3>
-		<div>This creates a quadratic curve from the offset to x and y with cpX and cpY as control point and updates the offset to x and y.</div>
+		Adds an [page:EllipseCurve EllipseCurve] to the path, positioned relative to [page:.currentPoint].
+		</div>
 
-		<h3>[method:null bezierCurveTo]( [page:Float cp1X], [page:Float cp1Y], [page:Float cp2X], [page:Float cp2Y], [page:Float x], [page:Float y] )</h3>
-		<div>This creates a bezier curve from the last offset to x and y with cp1X, cp1Y and cp1X, cp1Y as control points and updates the offset to x and y.</div>
 
-		<h3>[method:null splineThru] ( [page:Array points] ) </h3>
-		<div>points - An array of [page:Vector2]s</div>
-		<div>Connects a new [page:SplineCurve] onto the path.</div>
+		<h3>[method:null bezierCurveTo]( [page:Float cp1X], [page:Float cp1Y], [page:Float cp2X], [page:Float cp2Y], [page:Float x], [page:Float y] )</h3>
+		<div>This creates a bezier curve from [page:.currentPoint] with cp1X, cp1Y and cp1X, cp1Y as control points and updates [page:.currentPoint] to x and y.</div>
 
-		<h3>[method:null arc]( [page:Float x], [page:Float y], [page:Float radius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise] )</h3>
+		<h3>[method:null fromPoints]( [page:Array vector2s] )</h3>
 		<div>
-		x, y -- The center of the arc offset from the last call
-		radius -- The radius of the arc
-		startAngle -- The start angle in radians
-		endAngle -- The end angle in radians
-		clockwise -- Sweep the arc clockwise. Defaults to false
-		</div>
-		<div>Draw an arc offset from the last call</div>
+			points --  array of [page:Vector2 Vector2s].<br /><br />
 
-		<h3>[method:null absarc]( [page:Float x], [page:Float y], [page:Float radius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise] )</h3>
-		<div>
-		x, y -- The absolute center of the arc
-		radius -- The radius of the arc
-		startAngle -- The start angle in radians
-		endAngle -- The end angle in radians
-		clockwise -- Sweep the arc clockwise. Defaults to false
+			Adds to the from the points. Points	are added to the [page:CurvePath.curves curves]
+			array as [page:LineCurve LineCurves].
 		</div>
-		<div>Draw an arc absolutely positioned</div>
 
 		<h3>[method:null ellipse]( [page:Float x], [page:Float y], [page:Float xRadius], [page:Float yRadius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise], [page:Float rotation] )</h3>
 		<div>
-		x, y -- The center of the ellipse offset from the last call
-		xRadius -- The radius of the ellipse in the x axis
-		yRadius -- The radius of the ellipse in the y axis
-		startAngle -- The start angle in radians
-		endAngle -- The end angle in radians
-		clockwise -- Sweep the ellipse clockwise. Defaults to false
-		rotation -- The rotation angle of the ellipse in radians, counterclockwise from the positive X axis. Optional, defaults to 0
+			x, y -- The center of the ellipse offset from the last call.<br />
+			xRadius -- The radius of the ellipse in the x axis.<br />
+			yRadius -- The radius of the ellipse in the y axis.<br />
+			startAngle -- The start angle in radians.<br />
+			endAngle -- The end angle in radians.<br />
+			clockwise -- Sweep the ellipse clockwise. Defaults to *false*.<br />
+			rotation -- The rotation angle of the ellipse in radians, counterclockwise from the positive X axis. Optional, defaults to *0*.<br /><br />
+
+			Adds an [page:EllipseCurve EllipseCurve] to the path, positioned relative to [page:.currentPoint].
 		</div>
-		<div>Draw an ellipse offset from the last call</div>
 
-		<h3>[method:null absellipse]( [page:Float x], [page:Float y], [page:Float xRadius], [page:Float yRadius], [page:Float startAngle], [page:Float endAngle], [page:Float clockwise], [page:Float rotation] )</h3>
-		<div>
-		x, y -- The absolute center of the ellipse
-		xRadius -- The radius of the ellipse in the x axis
-		yRadius -- The radius of the ellipse in the y axis
-		startAngle -- The start angle in radians
-		endAngle -- The end angle in radians
-		clockwise -- Sweep the ellipse clockwise. Defaults to false
-		rotation -- The rotation angle of the ellipse in radians, counterclockwise from the positive X axis. Optional, defaults to 0
-		</div>
-		<div>Draw an ellipse absolutely positioned</div>
+		<h3>[method:null lineTo]( [page:Float x], [page:Float y] )</h3>
+		<div>Connects a [page:LineCurve] from [page:.currentPoint] to x, y onto the path.</div>
 
-		<h3>[method:Array toShapes]( [page:Boolean isCCW], [page:Boolean noHoles] )</h3>
-		<div>
-		isCCW -- Changes how solids and holes are generated<br/>
-		noHoles -- Whether or not to generate holes
-		</div>
+
+		<h3>[method:null moveTo]( [page:Float x], [page:Float y] )</h3>
+		<div>Move the [page:.currentPoint] to x, y.</div>
+
+
+		<h3>[method:null quadraticCurveTo]( [page:Float cpX], [page:Float cpY], [page:Float x], [page:Float y] )</h3>
+		<div>Creates a quadratic curve from [page:.currentPoint] with cpX and cpY as control point and updates [page:.currentPoint] to x and y.</div>
+
+		<h3>[method:null splineThru] ( [page:Array points] ) </h3>
 		<div>
-		Converts the Path into an array of Shapes. By default solid shapes are defined clockwise (CW) and holes are defined counterclockwise (CCW). If isCCW is set to true,
-		then those are flipped. If the paramater noHoles is set to true then all paths are set as solid shapes and isCCW is ignored.
-		<br/>
+			points - An array of [page:Vector2 Vector2s]<br /><br />
 
+			Connects a new [page:SplineCurve] onto the path.
 		</div>
 
-
 		<h2>Source</h2>
 
 		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]

docs/api/extras/core/Shape.html

@@ -52,71 +52,37 @@
 
 
 		<h2>Properties</h2>
-
+		<div>See the base [page:Path] class for common properties.</div>
 
 		<h3>[property:array holes]</h3>
-		<div>
-		An array of [page:Path paths] that define the holes in the shape.
-		</div>
+		<div>An array of [page:Path paths] that define the holes in the shape.</div>
 
 		<h2>Methods</h2>
-
-
-		<h3>[method:ShapeGeometry makeGeometry]( [page:Object options] )</h3>
-		<div>
-		options -- This is passed as the second argument to [page:ShapeGeometry ShapeGeometry]
-		</div>
-		<div>
-		Convenience method to return ShapeGeometry
-		</div>
+		<div>See the base [page:Path] class for common methods.</div>
 
 		<h3>[method:Array extractAllPoints]( [page:Integer divisions] )</h3>
 		<div>
-		divisions -- The number of divisions to create on the shape
-		</div>
-		<div>
-		Get points of shape and holes (keypoints based on segments parameter)
-		</div>
+		divisions -- The fineness of the result.<br /><br />
 
-		<h3>[method:ExtrudeGeometry extrude]( [page:Object options] )</h3>
-		<div>
-		options -- This is passed as the second argument to [page:ExtrudeGeometry ExtrudeGeometry]
-		</div>
-		<div>
-		Convenience method to return ExtrudeGeometry
+		Call [page:Curve.getPoints getPoints] on the shape and the [page:.holes] array, and return an object of the form:
+		<code>
+{
+	shape
+	holes
+}
+		</code>
+		where shape and holes are arrays of [page:Vector2 Vector2s].
 		</div>
 
 		<h3>[method:Object extractPoints]( [page:Integer divisions] )</h3>
-		<div>
-		divisions -- The number of divisions to create on the shape
-		</div>
-		<div>
-		Returns an object with a *shape* and *holes* property that each reference an array of [page:Vector2 Vector2s].
-		</div>
+		<div>This is identical to [page:.extractAllPoints].</div>
 
-		<h3>[method:Object extractAllSpacedPoints]( [page:Integer divisions] )</h3>
-		<div>
-		divisions -- The number of divisions to create on the shape
-		</div>
-		<div>
-		Returns an object with a *shape* and *holes* property that each reference an array of [page:Vector2 Vector2s]. The
-		points will all be equally spaced along the shape.
-		</div>
 
 		<h3>[method:Array getPointsHoles]( [page:Integer divisions] )</h3>
 		<div>
-		divisions -- The number of divisions to create on the shape
-		</div>
-		<div>
-		Get an array of [page Vector2 Vector2s] that represent the holes in the shape.
-		</div>
+		divisions -- The fineness of the result.<br /><br />
 
-		<h3>[method:Array getSpacedPointsHoles]( [page:Integer divisions] )</h3>
-		<div>
-		divisions -- The number of divisions to create on the shape
-		</div>
-		<div>
-		Get an array of equally spaced [page Vector2 Vector2s] that represent the holes in the shape.
+		Get an array of [page:Vector2 Vector2s] that represent the holes in the shape.
 		</div>
 
 		<h2>Source</h2>