From 943d68e9848056a3d0e55b22fb548f541e537c52 Mon Sep 17 00:00:00 2001
From: JetStarBlues <JetStarBlues@users.noreply.github.com>
Date: Mon, 14 Jun 2021 18:38:37 -0600
Subject: [PATCH 1/2] Replaces the current `specularColor()` example with one
 that aims to better demonstrate the function.

---
 src/webgl/light.js | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/src/webgl/light.js b/src/webgl/light.js
index e16c789d16..f1ec8a1c7b 100644
--- a/src/webgl/light.js
+++ b/src/webgl/light.js
@@ -113,6 +113,8 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  * @example
  * <div>
  * <code>
+ * let setSpecularColor = true;
+ *
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
@@ -120,20 +122,31 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  *
  * function draw() {
  *   background(0);
- *   shininess(20);
- *   ambientLight(50);
- *   specularColor(255, 0, 0);
- *   pointLight(255, 0, 0, 0, -50, 50);
- *   specularColor(0, 255, 0);
- *   pointLight(0, 255, 0, 0, 50, 50);
- *   specularMaterial(255);
- *   sphere(40);
+ *
+ *   ambientLight(60);
+ *
+ *   // add point light to showcase specular color
+ *   let locX = mouseX - width / 2;
+ *   let locY = mouseY - height / 2;
+ *   if (setSpecularColor) {
+ *     specularColor(255, 0, 0); // red specular highlight
+ *   }
+ *   pointLight(200, 200, 200, locX, locY, 50); // white light
+ *
+ *   specularMaterial(150);
+ *   shininess(50);
+ *   sphere(30, 64, 64);
+ * }
+ *
+ * function mouseClicked() {
+ *   setSpecularColor = !setSpecularColor;
  * }
  * </code>
  * </div>
  *
  * @alt
- * different specular light sources from top and bottom of canvas
+ * Sphere with specular highlight. Clicking the mouse toggles the
+ * specular highlight color between red and the default white.
  */
 
 /**

From a2e8dfa08bec7e7a8df16630a3cab9ea6fe92317 Mon Sep 17 00:00:00 2001
From: JetStarBlues <JetStarBlues@users.noreply.github.com>
Date: Sun, 17 Oct 2021 17:18:13 -0600
Subject: [PATCH 2/2] Improve clarity of `specularColor()` example

---
 src/webgl/light.js | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/webgl/light.js b/src/webgl/light.js
index daf2829642..e8a067c9bf 100644
--- a/src/webgl/light.js
+++ b/src/webgl/light.js
@@ -113,7 +113,7 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  * @example
  * <div>
  * <code>
- * let setSpecularColor = true;
+ * let setRedSpecularColor = true;
  *
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
@@ -125,21 +125,26 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  *
  *   ambientLight(60);
  *
- *   // add point light to showcase specular color
- *   let locX = mouseX - width / 2;
- *   let locY = mouseY - height / 2;
- *   if (setSpecularColor) {
+ *   // add a point light to showcase specular color
+ *   // -- use mouse location to position the light
+ *   let lightPosX = mouseX - width / 2;
+ *   let lightPosY = mouseY - height / 2;
+ *   // -- set the light's specular color
+ *   if (setRedSpecularColor) {
  *     specularColor(255, 0, 0); // red specular highlight
  *   }
- *   pointLight(200, 200, 200, locX, locY, 50); // white light
+ *   // -- create the light
+ *   pointLight(200, 200, 200, lightPosX, lightPosY, 50); // white light
  *
+ *   // use specular material with high shininess
  *   specularMaterial(150);
  *   shininess(50);
+ *
  *   sphere(30, 64, 64);
  * }
  *
  * function mouseClicked() {
- *   setSpecularColor = !setSpecularColor;
+ *   setRedSpecularColor = !setRedSpecularColor;
  * }
  * </code>
  * </div>