Minor changes to the wording used in the following lighting methods, with the goal of improving clarity.

Borrowed some descriptions from the Processing Reference.

ambientLight()

1) Reword

Current:

Creates an ambient light with a color. Ambient light is light that comes from everywhere on the canvas. It has no particular source.

Change:

Creates an ambient light with the given color.

Ambient light does not come from a specific direction. Objects are evenly lit from all sides. Ambient lights are almost always used in combination with other types of lights.

2) Add disclaimer

Change:

Note: lights need to be called (whether directly or indirectly) within draw() to remain persistent in a looping program. Placing them in setup() will cause them to only have an effect the first time through the loop.

3) Be consistent with params

Use same parameter descriptions as color() reference.

Current:

alpha
the alpha value (Optional)

gray
a gray value

color
p5.Color: the ambient light color

Change:

alpha
alpha value relative to current color range (default is 0-255)

gray
Number: number specifying value between white and black

color
p5.Color: color as a p5.Color

4) Fix comments in examples

directionalLight

1) Reword

Current:

Creates a directional light with a color and a direction

A maximum of 5 directionalLight can be active at one time

Change:

Creates a directional light with the given color and direction.

Directional light comes from one direction.
The direction is specified as numbers inclusively between -1 and 1. For example, setting the direction as (0, -1, 0) will cause the geometry to be lit from below (since the light will be facing directly upwards). Similarly, setting the direction as (1, 0, 0) will cause the geometry to be lit from the left (since the light will be facing directly rightwards).

A maximum of 5 directional lights can be active at once.

2) Add disclaimer

Change:

Note: lights need to be called (whether directly or indirectly) within draw() to remain persistent in a looping program. Placing them in setup() will cause them to only have an effect the first time through the loop.

3) Rename position parameter to direction

4) Be consistent with params

Current:

v1
red or hue value (depending on the current color mode),

v2
green or saturation value

v3
blue or brightness value

position
the direction of the light

color
Number[]|String|p5.Color:
color Array, CSS color string, or p5.Color value

x
x axis direction

y
y axis direction

z
z axis direction

Change:

v1
red or hue value relative to the current color range

v2
green or saturation value relative to the current color range

v3
blue or brightness value relative to the current color range

direction
direction of light as a p5.Vector

color
p5.Color|Number[]|String:
color as a p5.Color, as an array, or as a CSS string

x
x component of direction (inclusive range of -1 to 1)

y
y component of direction (inclusive range of -1 to 1)

z
z component of direction (inclusive range of -1 to 1)

pointLight

1) Reword

Note, I got the description of what a point light is from the three.js documentation, since there was nothing on the Processing page.

Current:

Creates a point light with a color and a light position

A maximum of 5 pointLight can be active at one time

Change:

Creates a point light with the given color and position.

A point light emits light from a single point in all directions.

A maximum of 5 point lights can be active at once.

2) Add disclaimer

Change:

Note: lights need to be called (whether directly or indirectly) within draw() to remain persistent in a looping program. Placing them in setup() will cause them to only have an effect the first time through the loop.

3) Be consistent with params

Current:

v1
red or hue value (depending on the current color mode),

v2
green or saturation value

v3
blue or brightness value

x
x axis position

y
y axis position

z
z axis position

position
the position of the light

color
Number[]|String|p5.Color:
color Array, CSS color string, or p5.Color value

Change:

v1
red or hue value relative to the current color range

v2
green or saturation value relative to the current color range

v3
blue or brightness value relative to the current color range

position
position of light as a p5.Vector

color
p5.Color|Number[]|String:
color as a p5.Color, as an array, or as a CSS string

x
x component of position

y
y component of position

z
z component of position

spotLight

1) Reword

Note, I got the description of what a spot light is from the three.js documentation, since there was nothing on the Processing page.

I don't have enough background knowledge to understand what the angle and concentration parameters are supposed to. Do the current descriptions make sense?

Current:

Creates a spotlight with a given color, position, direction of light, angle and concentration. Here, angle refers to the opening or aperture of the cone of the spotlight, and concentration is used to focus the light towards the center. Both angle and concentration are optional, but if you want to provide concentration, you will also have to specify the angle.

A maximum of 5 spotLight can be active at one time

Change:

Creates a spot light with the given color, position, light direction, angle, and concentration.

A spot light emits light from a single point in one direction along a conical shape. The angle parameter is used to determine the radius of the cone. And the concentration parameter is used to focus the light towards the center of the cone. Both parameters are optional, however if you want to specify concentration, you must also specify angle.

The minimum concentration value is 1.

A maximum of 5 spot lights can be active at once.

2) Add disclaimer

Change:

Note: lights need to be called (whether directly or indirectly) within draw() to remain persistent in a looping program. Placing them in setup() will cause them to only have an effect the first time through the loop.

3) Rename conc parameter to concentration

4) Be consistent with params

Current:

v1
red or hue value (depending on the current color mode),

v2
green or saturation value

v3
blue or brightness value

x
x axis position

y
y axis position

z
z axis position

rx
x axis direction of light

ry
y axis direction of light

rz
z axis direction of light

angle
optional parameter for angle. Defaults to PI/3 (Optional)

conc
optional parameter for concentration. Defaults to 100 (Optional)

color
Number[]|String|p5.Color:
color Array, CSS color string, or p5.Color value

position
the position of the light

direction
the direction of the light

Change:

v1
red or hue value relative to the current color range

v2
green or saturation value relative to the current color range

v3
blue or brightness value relative to the current color range

x
x component of position

y
y component of position

z
z component of position

rx
x component of light direction (inclusive range of -1 to 1)

ry
y component of light direction (inclusive range of -1 to 1)

rz
z component of light direction (inclusive range of -1 to 1)

angle
angle of cone. Defaults to PI/3

concentration
concentration of cone. Defaults to 100

color
p5.Color|Number[]|String:
color as a p5.Color, as an array, or as a CSS string

position
position of light as a p5.Vector

direction
direction of light as a p5.Vector

lightFalloff

1) Reword

Current:

Sets the falloff rates for point lights. It affects only the elements which are created after it in the code. The default value is lightFalloff(1.0, 0.0, 0.0), and the parameters are used to calculate the falloff with the following equation:

Change:

Sets the falloff rate for pointLight() and spotLight().

lightFalloff() affects only the lights which are created after it in the code.

The constant, linear, an quadratic parameters are used to calculate falloff as follows:

2) Improve example

Separate PR over here.

specularColor

1) Reword

Current:

Set's the color of the specular highlight when using a specular material and specular light.

This method can be combined with specularMaterial() and shininess() functions to set specular highlights. The default color is white, ie (255, 255, 255), which is used if this method is not called before specularMaterial(). If this method is called without specularMaterial(), There will be no effect.

Change:

Sets the color of the specular highlight of a non-ambient light (i.e. all lights except ambientLight()).

specularColor() affects only the lights which are created after it in the code.

This function is used in combination with specularMaterial(). If a geometry does not use specularMaterial(), this function will have no effect.

The default color is white (255, 255, 255), which is used if specularColor() is not explicitly called.

2) Be consistent with params

Current:

value
a color string

gray
a gray value

values
an array containing the red,green,blue & and alpha components of the color

color
the ambient light color

Change:

value
color as a CSS string

gray
number specifying value between white and black

values
color as an array containing the red, green, and blue components

color
color as a p5.Color

3) Improve example

Separate PR over here.

lights

1) Reword

Current:

Sets the default ambient and directional light. The defaults are ambientLight(128, 128, 128) and directionalLight(128, 128, 128, 0, 0, -1).
Lights need to be included in the draw() to remain persistent in a looping program. Placing them in the setup() of a looping program will cause them to only have an effect the first time through the loop.

Change:

Places an ambient and directional light in the scene. The lights are set to ...

Note: lights need to be called (whether directly or indirectly) within draw() to remain persistent in a looping program. Placing them in setup() will cause them to only have an effect the first time through the loop.

noLights()

2) Reword

Current:

This function will remove all the lights from the sketch for the subsequent materials rendered. It affects all the subsequent methods. Calls to lighting methods made after noLights() will re-enable lights in the sketch.

Change:

Removes all lights present in a sketch.

All subsequent geometry is rendered without lighting (until a new light is created with a call to one of the lighting functions (lights(), ambientLight(), directionalLight(), pointLight(), spotLight()).

3) Improve example

Separate PR over here.

General

1) Move around variants so that consistent across

directionalLight (change)

directionalLight(v1, v2, v3, x, y, z)
directionalLight(v1, v2, v3, direction)
directionalLight(color, x, y, z)
directionalLight(color, direction)

pointLight (no change)

pointLight(v1, v2, v3, x, y, z)
pointLight(v1, v2, v3, position)
pointLight(color, x, y, z)
pointLight(color, position)

Screenshots of the change

ambientLight

directionalLight

pointLight

spotLight

lights

noLights

lightFalloff

specularColor