WebGL mode documentation improvements

src/core/constants.js

@@ -22,8 +22,21 @@ export const VERSION =
  */
 export const P2D = 'p2d';
 /**
- * One of the two render modes in p5.js: P2D (default renderer) and WEBGL
- * Enables 3D render by introducing the third dimension: Z
+ * One of the two render modes in p5.js, used for computationally intensive tasks like 3D rendering and shaders.
+ *
+ * `WEBGL` differs from the default <a href="/#/p5/P2D">`P2D`</a> renderer in the following ways:
+ *
+ * - **Coordinate System** - When drawing in `WEBGL` mode, the origin point (0,0,0) is located at the center of the screen, not the top-left corner. See <a href="https://p5js.org/learn/getting-started-in-webgl-coords-and-transform.html">the learn page about coordinates and transformations</a>.
+ * - **3D Shapes** - `WEBGL` mode can be used to draw 3-dimensional shapes like <a href="/#/p5/box">box()</a>, <a href="/#/p5/sphere">sphere()</a>, <a href="/#/p5/cone">cone()</a>, and <a href="/#Shape3D%20Primitives">more</a>. See <a href="https://p5js.org/learn/getting-started-in-webgl-custom-geometry.html">the learn page about custom geometry</a> to make more complex objects.
+ * - **Textures** - A texture is like a skin that wraps onto a shape. See <a href="https://github.com/processing/p5.js/wiki/Getting-started-with-WebGL-in-p5#textures">the wiki section about textures</a> for examples of mapping images onto surfaces with textures.
+ * - **Materials and Lighting** - `WEBGL` offers different types of lights like <a href="/#/p5/ambientLight">ambientLight()</a> to place around a scene. Materials like <a href="/#/p5/specularMaterial">specularMaterial()</a> reflect the lighting to convey shape and depth. See <a href="https://p5js.org/learn/getting-started-in-webgl-appearance.html">the learn page for styling and appearance</a> to experiment with different combinations.
+ * - **Camera** - The viewport of a `WEBGL` sketch can be adjusted by changing camera attributes. See <a href="https://p5js.org/learn/getting-started-in-webgl-appearance.html#camera">the learn page section about cameras</a> for an explanation of camera controls.
+ * - **Text** - `WEBGL` requires opentype/truetype font files to be preloaded using <a href="/#/p5/loadFont">loadFont()</a>. See <a href="https://github.com/processing/p5.js/wiki/Getting-started-with-WebGL-in-p5#text">the wiki section about text</a> for details, along with a workaround.
+ * - **Shaders** - Shaders are hardware accelerated programs that can be used for a variety of effects and graphics. See the <a href="https://p5js.org/learn/getting-started-in-webgl-shaders.html">introduction to shaders</a> to get started with shaders in p5.js.
+ * - **Graphics Acceleration** - `WEBGL` mode uses the graphics card instead of the CPU, so it may help boost the performance of your sketch (example: drawing more shapes on the screen at once).
+ *
+ * To learn more about WEBGL mode, check out <a href="https://p5js.org/learn/#:~:text=Getting%20Started%20in%20WebGL">all the interactive WEBGL tutorials</a> in the "Learn" section of this website, or read the wiki article <a href="https://github.com/processing/p5.js/wiki/Getting-started-with-WebGL-in-p5">"Getting started with WebGL in p5"</a>.
+ *
  * @property {String} WEBGL
  * @final
  */

src/core/shape/2d_primitives.js

@@ -172,6 +172,15 @@ p5.prototype._normalizeArcAngles = (
  * </code>
  * </div>
  *
+ * <div>
+ * <code>
+ * createCanvas(100, 100, WEBGL);
+ * arc(0, 0, 80, 80, 0, PI + QUARTER_PI, PIE, 7);
+ * describe(
+ *   'ellipse with a quarter missing, and the outline is segmented instead of curved'
+ * );
+ * </code>
+ * </div>
  */
 p5.prototype.arc = function(x, y, w, h, start, stop, mode, detail) {
   p5._validateParameters('arc', arguments);
@@ -375,16 +384,27 @@ p5.prototype._renderEllipse = function(x, y, w, h, detailX) {
  * </code>
  * </div>
  *
+ * <div>
+ * <code>
+ * createCanvas(100, 100, WEBGL);
+ * strokeWeight(7);
+ * line(0, 0, 0, 30, 0, 0);
+ * line(0, 0, 0, 0, 30, 0);
+ * line(-30, -30, -30, 30, 30, 30);
+ * describe('two lines mark the flat x and y axes while a third line spans diagonally through the third dimension');
+ * </code>
+ * </div>
+ *
  */
 
 /**
  * @method line
  * @param  {Number} x1
  * @param  {Number} y1
- * @param  {Number} z1 the z-coordinate of the first point
+ * @param  {Number} z1 the z-coordinate of the first point (for WEBGL mode)
  * @param  {Number} x2
  * @param  {Number} y2
- * @param  {Number} z2 the z-coordinate of the second point
+ * @param  {Number} z2 the z-coordinate of the second point (for WEBGL mode)
  * @chainable
  */
 p5.prototype.line = function(...args) {

src/webgl/3d_primitives.js

@@ -988,6 +988,9 @@ p5.prototype.torus = function(radius, tubeRadius, detailX, detailY) {
 ///////////////////////
 /// 2D primitives
 /////////////////////////
+//
+// Note: Documentation is not generated on the p5.js website for functions on
+// the p5.RendererGL prototype.
 
 /**
  * Draws a point, a coordinate in space at the dimension of one pixel,