Merge pull request #7032 from nickmcintyre/ref-data-array

Update array references

src/utilities/array_functions.js

@@ -183,28 +183,101 @@ p5.prototype.shorten = function(list) {
 };
 
 /**
- * Randomizes the order of the elements of an array. Implements
- * <a href='http://Bost.Ocks.org/mike/shuffle/' target=_blank>
- * Fisher-Yates Shuffle Algorithm</a>.
+ * Shuffles the elements of an array.
+ *
+ * The first parameter, `array`, is the array to be shuffled. For example,
+ * calling `shuffle(myArray)` will shuffle the elements of `myArray`. By
+ * default, the original array won’t be modified. Instead, a copy will be
+ * created, shuffled, and returned.
+ *
+ * The second parameter, `modify`, is optional. If `true` is passed, as in
+ * `shuffle(myArray, true)`, then the array will be shuffled in place without
+ * making a copy.
  *
  * @method shuffle
- * @param  {Array}   array  Array to shuffle
- * @param  {Boolean} [bool] modify passed array
- * @return {Array}   shuffled Array
+ * @param  {Array} array array to shuffle.
+ * @param  {Boolean} [bool] if `true`, shuffle the original array in place. Defaults to `false`.
+ * @return {Array} shuffled array.
+ *
  * @example
- * <div><code>
+ * <div>
+ * <code>
+ * function setup() {
+ *   createCanvas(100, 100);
+ *
+ *   background(200);
+ *
+ *   // Create an array of colors.
+ *   let colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];
+ *
+ *   // Create a shuffled copy of the array.
+ *   let shuffledColors = shuffle(colors);
+ *
+ *   // Draw  a row of circles using the original array.
+ *   for (let i = 0; i < colors.length; i += 1) {
+ *     // Calculate the x-coordinate.
+ *     let x = (i + 1) * 12.5;
+ *
+ *     // Style the circle.
+ *     let c = colors[i];
+ *     fill(c);
+ *
+ *     // Draw the circle.
+ *     circle(x, 33, 10);
+ *   }
+ *
+ *   // Draw  a row of circles using the original array.
+ *   for (let i = 0; i < shuffledColors.length; i += 1) {
+ *     // Calculate the x-coordinate.
+ *     let x = (i + 1) * 12.5;
+ *
+ *     // Style the circle.
+ *     let c = shuffledColors[i];
+ *     fill(c);
+ *
+ *     // Draw the circle.
+ *     circle(x, 67, 10);
+ *   }
+ *
+ *   describe(
+ *     'Two rows of circles on a gray background. The top row follows the color sequence ROYGBIV. The bottom row has all the same colors but they are shuffled.'
+ *   );
+ * }
+ * </code>
+ * </div>
+ *
+ * <div>
+ * <code>
  * function setup() {
- *   let regularArr = ['ABC', 'def', createVector(), TAU, Math.E];
- *   print(regularArr);
- *   shuffle(regularArr, true); // force modifications to passed array
- *   print(regularArr);
- *
- *   // By default shuffle() returns a shuffled cloned array:
- *   let newArr = shuffle(regularArr);
- *   print(regularArr);
- *   print(newArr);
+ *   createCanvas(100, 100);
+ *
+ *   background(200);
+ *
+ *   // Create an array of colors.
+ *   let colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];
+ *
+ *   // Shuffle the array.
+ *   shuffle(colors, true);
+ *
+ *   // Draw  a row of circles using the original array.
+ *   for (let i = 0; i < colors.length; i += 1) {
+ *     // Calculate the x-coordinate.
+ *     let x = (i + 1) * 12.5;
+ *
+ *     // Style the circle.
+ *     let c = colors[i];
+ *     fill(c);
+ *
+ *     // Draw the circle.
+ *     circle(x, 50, 10);
+ *   }
+ *
+ *   describe(
+ *     'A row of colorful circles on a gray background. Their sequence changes each time the sketch runs.'
+ *   );
  * }
- * </code></div>
+ * </code>
+ * </div>
  */
 p5.prototype.shuffle = function(arr, bool) {
   const isView = ArrayBuffer && ArrayBuffer.isView && ArrayBuffer.isView(arr);