Update p5.strands hooks documentation based on reviewer feedback

Author: Abhayaj247

src/webgl/p5.strands.js

@@ -1,23 +1,28 @@
+/**
+ * @typedef {Object} Vertex
+ * @property {{x: number, y: number, z: number}} position - The position of the vertex in world space.
+ * @property {{x: number, y: number, z: number}} normal - The normal vector at the vertex in world space.
+ * @property {{x: number, y: number}} texCoord - The texture coordinates (x, y) for the vertex.
+ * @property {{r: number, g: number, b: number, a: number}} color - The color at the vertex.
+ */
+
 /**
  * @function getWorldInputs
  * @experimental
  * @description
- * Registers a callback to modify world-space vertex inputs for each vertex.
- * The callback receives an object with the following properties:
- *   - position: { x, y, z }
- *   - normal: { x, y, z }
- *   - texCoord: { x, y }
- *   - color: { r, g, b, a }
- * and should return a modified object with the same structure.
+ * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied.
  *
  * This hook is available in:
  * - {@link p5.baseMaterialShader}
  * - {@link p5.baseNormalShader}
  * - {@link p5.baseColorShader}
  * - {@link p5.baseStrokeShader}
  *
- * @param {function(inputs: { position: {x: number, y: number, z: number}, normal: {x: number, y: number, z: number}, texCoord: {x: number, y: number}, color: {r: number, g: number, b: number, a: number} }): object} callback
- *        A function that receives the current inputs and returns the modified inputs.
+ * @param {function(Vertex): Vertex} callback
+ *        A callback function which receives and returns a Vertex struct.
+ *
+ * @see {@link p5.baseMaterialShader}
+ * @see {@link p5.Shader#modify}
  *
  * @example
  * <div modernizr='webgl'>
@@ -28,7 +33,7 @@
  *   myShader = baseMaterialShader().modify(() => {
  *     getWorldInputs((inputs) => {
  *       // Move the vertex up and down in a wave
- *       inputs.position.y += 20 * Math.sin(millis() * 0.001 + inputs.position.x * 0.05);
+ *       inputs.position.y += 20 * sin(millis() * 0.001 + inputs.position.x * 0.05);
  *       return inputs;
  *     });
  *   });
@@ -49,26 +54,19 @@
  * @function combineColors
  * @experimental
  * @description
- * Registers a callback to customize how color components are combined in the fragment shader.
- * The callback receives an object with the following properties:
- *   - baseColor: { r, g, b }
- *   - opacity: number
- *   - ambientColor: { r, g, b }
- *   - specularColor: { r, g, b }
- *   - diffuse: { r, g, b }
- *   - ambient: { r, g, b }
- *   - specular: { r, g, b }
- *   - emissive: { r, g, b }
- * and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number).
+ * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to control the final color output of a material. The callback receives a ColorComponents struct and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number).
  *
  * This hook is available in:
  * - {@link p5.baseMaterialShader}
  * - {@link p5.baseNormalShader}
  * - {@link p5.baseColorShader}
  * - {@link p5.baseStrokeShader}
  *
- * @param {function(components: { baseColor: {r: number, g: number, b: number}, opacity: number, ambientColor: {r: number, g: number, b: number}, specularColor: {r: number, g: number, b: number}, diffuse: {r: number, g: number, b: number}, ambient: {r: number, g: number, b: number}, specular: {r: number, g: number, b: number}, emissive: {r: number, g: number, b: number} }): { color: {r: number, g: number, b: number}, opacity: number }} callback
- *        A function that receives the current color components and returns the final color and opacity.
+ * @param {function(ColorComponents): { color: {r: number, g: number, b: number}, opacity: number }} callback
+ *        A callback function which receives a ColorComponents struct and returns the final color and opacity.
+ *
+ * @see {@link p5.baseMaterialShader}
+ * @see {@link p5.Shader#modify}
  *
  * @example
  * <div modernizr='webgl'>
@@ -113,32 +111,38 @@
  * @function getPointSize
  * @experimental
  * @description
- * Registers a callback to modify the size of each point in the point shader.
- * The callback receives the current point size (number) and should return the new size (number).
+ * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number).
  *
  * This hook is available in:
- * - {@link p5.pointShader}
+ * - {@link p5.baseMaterialShader}
+ * - {@link p5.baseNormalShader}
+ * - {@link p5.baseColorShader}
+ * - {@link p5.baseStrokeShader}
  *
  * @param {function(size: number): number} callback
- *        A function that receives the current point size and returns the modified size.
+ *        A callback function which receives and returns the point size.
+ *
+ * @see {@link p5.baseMaterialShader}
+ * @see {@link p5.Shader#modify}
  *
  * @example
  * <div modernizr='webgl'>
  * <code>
  * let myShader;
  * function setup() {
  *   createCanvas(200, 200, WEBGL);
- *   myShader = pointShader().modify(() => {
+ *   myShader = baseMaterialShader().modify(() => {
  *     getPointSize((size) => {
- *       // Make points pulse
- *       return size * (1 + 0.5 * Math.sin(millis() * 0.001));
+ *       // Make points pulse in size over time
+ *       return size * (1.0 + 0.5 * sin(millis() * 0.002));
  *     });
  *   });
  * }
  * function draw() {
  *   background(255);
  *   shader(myShader);
- *   strokeWeight(10);
+ *   strokeWeight(20);
+ *   stroke('blue');
  *   point(0, 0);
  * }
  * </code>