Merge pull request #5307 from JetStarBlues/improveShaderDocumentation

Improve documentation clarity of shader methods

Author: stalgiag

src/webgl/material.js

@@ -10,21 +10,21 @@ import * as constants from '../core/constants';
 import './p5.Texture';
 
 /**
- * Loads a custom shader from the provided vertex and fragment
- * shader paths. The shader files are loaded asynchronously in the
+ * Creates a new <a href="#/p5.Shader">p5.Shader</a> object
+ * from the provided vertex and fragment shader files.
+ *
+ * The shader files are loaded asynchronously in the
  * background, so this method should be used in <a href="#/p5/preload">preload()</a>.
  *
- * For now, there are three main types of shaders. p5 will automatically
- * supply appropriate vertices, normals, colors, and lighting attributes
- * if the parameters defined in the shader match the names.
+ * Note, shaders can only be used in WEBGL mode.
  *
  * @method loadShader
  * @param {String} vertFilename path to file containing vertex shader
  * source code
  * @param {String} fragFilename path to file containing fragment shader
  * source code
  * @param {function} [callback] callback to be executed after loadShader
- * completes. On success, the Shader object is passed as the first argument.
+ * completes. On success, the p5.Shader object is passed as the first argument.
  * @param {function} [errorCallback] callback to be executed when an error
  * occurs inside loadShader. On error, the error is passed as the first
  * argument.
@@ -109,6 +109,11 @@ p5.prototype.loadShader = function(
 };
 
 /**
+ * Creates a new <a href="#/p5.Shader">p5.Shader</a> object
+ * from the provided vertex and fragment shader code.
+ *
+ * Note, shaders can only be used in WEBGL mode.
+ *
  * @method createShader
  * @param {String} vertSrc source code for the vertex shader
  * @param {String} fragSrc source code for the fragment shader
@@ -177,15 +182,22 @@ p5.prototype.createShader = function(vertSrc, fragSrc) {
 };
 
 /**
- * The <a href="#/p5/shader">shader()</a> function lets the user provide a custom shader
- * to fill in shapes in WEBGL mode. Users can create their
- * own shaders by loading vertex and fragment shaders with
- * <a href="#/p5/loadShader">loadShader()</a>.
+ * Sets the <a href="#/p5.Shader">p5.Shader</a> object to
+ * be used to render subsequent shapes.
+ *
+ * Custom shaders can be created using the
+ * <a href="#/p5/createShader">createShader()</a> and
+ * <a href="#/p5/loadShader">loadShader()</a> functions.
+ *
+ * Use <a href="#/p5/resetShader">resetShader()</a> to
+ * restore the default shaders.
+ *
+ * Note, shaders can only be used in WEBGL mode.
  *
  * @method shader
  * @chainable
- * @param {p5.Shader} [s] the desired <a href="#/p5.Shader">p5.Shader</a> to use for rendering
- * shapes.
+ * @param {p5.Shader} s the <a href="#/p5.Shader">p5.Shader</a> object
+ * to use for rendering shapes.
  *
  * @example
  * <div modernizr='webgl'>
@@ -268,9 +280,9 @@ p5.prototype.shader = function(s) {
 };
 
 /**
- * This function restores the default shaders in WEBGL mode. Code that runs
- * after resetShader() will not be affected by previously defined
- * shaders. Should be run after <a href="#/p5/shader">shader()</a>.
+ * Restores the default shaders. Code that runs after resetShader()
+ * will not be affected by the shader previously set by
+ * <a href="#/p5/shader">shader()</a>
  *
  * @method resetShader
  * @chainable

src/webgl/p5.Shader.js

@@ -294,17 +294,21 @@ p5.Shader.prototype.useProgram = function() {
 };
 
 /**
- * Wrapper around gl.uniform functions.
- * As we store uniform info in the shader we can use that
- * to do type checking on the supplied data and call
- * the appropriate function.
+ * Used to set the uniforms of a
+ * <a href="#/p5.Shader">p5.Shader</a> object.
+ *
+ * Uniforms are used as a way to provide shader programs
+ * (which run on the GPU) with values from a sketch
+ * (which runs on the CPU).
+ *
  * @method setUniform
  * @chainable
- * @param {String} uniformName the name of the uniform in the
- * shader program
- * @param {Object|Number|Boolean|Number[]} data the data to be associated
- * with that uniform; type varies (could be a single numerical value, array,
- * matrix, or texture / sampler reference)
+ * @param {String} uniformName the name of the uniform.
+ * Must correspond to the name used in the vertex and fragment shaders
+ * @param {Boolean|Number|Number[]|p5.Image|p5.Graphics|p5.MediaElement}
+ * data the data to associate with the uniform. The type can be
+ * a boolean (true/false), a number, an array of numbers, or
+ * an image (p5.Image, p5.Graphics, p5.MediaElement)
  *
  * @example
  * <div modernizr='webgl'>