Improve documentation clarity of some of the camera methods

Author: JetStarBlues

src/webgl/p5.Camera.js

@@ -11,22 +11,22 @@ import p5 from '../core/main';
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- * Sets the camera position for a 3D sketch. Parameters for this function define
- * the position for the camera, the center of the sketch (where the camera is
- * pointing), and an up direction (the orientation of the camera).
+ * Sets the position of the current camera in a 3D sketch.
+ * Parameters for this function define the camera's position,
+ * the center of the sketch (where the camera is pointing),
+ * and an up direction (the orientation of the camera).
  *
  * This function simulates the movements of the camera, allowing objects to be
  * viewed from various angles. Remember, it does not move the objects themselves
- * but the camera instead. For example when centerX value is positive, the camera
- * is rotating to the right side of the sketch, so the object would seem like
- * moving to the left.
+ * but the camera instead. For example when the centerX value is positive,
+ * and the camera is rotating to the right side of the sketch,
+ * the object will seem like it's moving to the left.
  *
  * See this <a href = "https://www.openprocessing.org/sketch/740258">example</a>
  * to view the position of your camera.
  *
- * When called with no arguments, this function creates a default camera
- * equivalent to
- * camera(0, 0, (height/2.0) / tan(PI*30.0 / 180.0), 0, 0, 0, 0, 1, 0);
+ * If no parameters are given, the following default is used:
+ * camera(0, 0, (height/2) / tan(PI/6), 0, 0, 0, 0, 1, 0)
  * @method camera
  * @constructor
  * @for p5
@@ -113,18 +113,19 @@ p5.prototype.camera = function(...args) {
 };
 
 /**
- * Sets a perspective projection for the camera in a 3D sketch. This projection
- * represents depth through foreshortening: objects that are close to the camera
- * appear their actual size while those that are further away from the camera
- * appear smaller. The parameters to this function define the viewing frustum
+ * Sets a perspective projection for the current camera in a 3D sketch.
+ * This projection represents depth through foreshortening: objects
+ * that are close to the camera appear their actual size while those
+ * that are further away from the camera appear smaller.
+ *
+ * The parameters to this function define the viewing frustum
  * (the truncated pyramid within which objects are seen by the camera) through
  * vertical field of view, aspect ratio (usually width/height), and near and far
  * clipping planes.
  *
- * When called with no arguments, the defaults
- * provided are equivalent to
- * perspective(PI/3.0, width/height, eyeZ/10.0, eyeZ*10.0), where eyeZ
- * is equal to ((height/2.0) / tan(PI*60.0/360.0));
+ * If no parameters are given, the following default is used:
+ * perspective(PI/3, width/height, eyeZ/10, eyeZ*10),
+ * where eyeZ is equal to ((height/2) / tan(PI/6)).
  * @method  perspective
  * @for p5
  * @param  {Number} [fovy]   camera frustum vertical field of view,
@@ -173,14 +174,18 @@ p5.prototype.perspective = function(...args) {
 };
 
 /**
- * Sets an orthographic projection for the camera in a 3D sketch and defines a
- * box-shaped viewing frustum within which objects are seen. In this projection,
- * all objects with the same dimension appear the same size, regardless of
- * whether they are near or far from the camera. The parameters to this
- * function specify the viewing frustum where left and right are the minimum and
- * maximum x values, top and bottom are the minimum and maximum y values, and near
- * and far are the minimum and maximum z values. If no parameters are given, the
- * default is used: ortho(-width/2, width/2, -height/2, height/2).
+ * Sets an orthographic projection for the current camera in a 3D sketch
+ * and defines a box-shaped viewing frustum within which objects are seen.
+ * In this projection, all objects with the same dimension appear the same
+ * size, regardless of whether they are near or far from the camera.
+ *
+ * The parameters to this function specify the viewing frustum where
+ * left and right are the minimum and maximum x values, top and bottom are
+ * the minimum and maximum y values, and near and far are the minimum and
+ * maximum z values.
+ *
+ * If no parameters are given, the following default is used:
+ * ortho(-width/2, width/2, -height/2, height/2).
  * @method  ortho
  * @for p5
  * @param  {Number} [left]   camera frustum left plane
@@ -229,7 +234,8 @@ p5.prototype.ortho = function(...args) {
 };
 
 /**
- * Sets a perspective matrix as defined by the parameters.
+ * Sets the frustum of the current camera as defined by
+ * the parameters.
  *
  * A frustum is a geometric form: a pyramid with its top
  * cut off. With the viewer's eye at the imaginary top of
@@ -242,6 +248,8 @@ p5.prototype.ortho = function(...args) {
  * This can be achieved more simply in many cases by using
  * <a href="https://p5js.org/reference/#/p5/perspective">perspective()</a>.
  *
+ * If no parameters are given, the following default is used:
+ * frustum(-width/2, width/2, -height/2, height/2, 0, max(width, height)).
  * @method frustum
  * @for p5
  * @param  {Number} [left]   camera frustum left plane
@@ -295,9 +303,22 @@ p5.prototype.frustum = function(...args) {
 ////////////////////////////////////////////////////////////////////////////////
 
 /**
- * Creates a new <a href="#/p5.Camera">p5.Camera</a> object and tells the
- * renderer to use that camera.
- * Returns the p5.Camera object.
+ * Creates a new <a href="#/p5.Camera">p5.Camera</a> object and sets it
+ * as the current (active) camera.
+ *
+ * The new camera is initialized with a default position
+ * (see <a href="#/p5.Camera/camera">camera()</a>)
+ * and a default perspective projection
+ * (see <a href="#/p5.Camera/perspective">perspective()</a>).
+ * Its properties can be controlled with the <a href="#/p5.Camera">p5.Camera</a>
+ * methods.
+ *
+ * Note: Every 3D sketch starts with a default camera initialized.
+ * This camera can be controlled with the global methods
+ * <a href="#/p5/camera">camera()</a>,
+ * <a href="#/p5/perspective">perspective()</a>, <a href="#/p5/ortho">ortho()</a>,
+ * and <a href="#/p5/frustum">frustum()</a> if it is the only camera
+ * in the scene.
  * @method createCamera
  * @return {p5.Camera} The newly created camera object.
  * @for p5
@@ -1705,8 +1726,8 @@ p5.Camera.prototype._isActive = function() {
 };
 
 /**
- * Sets rendererGL's current camera to a p5.Camera object.  Allows switching
- * between multiple cameras.
+ * Sets the current (active) camera of a 3D sketch.
+ * Allows for switching between multiple cameras.
  * @method setCamera
  * @param  {p5.Camera} cam  p5.Camera object
  * @for p5