New FES Contributor Docs + FES Survey Link (#5460)

* inline doc organization

* new links

* fix: Update the rem instance method to be chainable

* chore: Adjust formatting

* fes ref + dev doc + inline doc updates

* edited for clarity

* updated reflecting comments from kate

Co-authored-by: Aaron Casanova <[email protected]>
Co-authored-by: Aaron Casanova <[email protected]>
Co-authored-by: evelyn masso <[email protected]>

Author: 3 people

contributor_docs/fes_reference_dev_notes.md

@@ -1,9 +1,12 @@
-// Different browsers may use different error strings for the same error.
-// Extracting info from them is much easier and cleaner if we have a predefined
-// lookup against which we try and match the errors obtained from the browser,
-// classify them into types and extract the required information. The contents
-// of this file serve as that lookup. The FES can use this to give a simplified
-// explanation for all kinds of errors.
+// This contains a data table used by ./fes_core.js/fesErrorMonitor().
+//
+// Note: Different browsers use different error strings for the same error.
+// Extracting info from the browser error messages is easier and cleaner
+// if we have a predefined lookup. This file serves as that lookup.
+// Using this lookup we match the errors obtained from the browser, classify
+// them into types and extract the required information.
+// The FES can use the extracted info to generate a friendly error message
+// for the matching error.
 const strings = {
   ReferenceError: [
     {

contributor_docs/friendly_error_system.md

@@ -2,78 +2,25 @@
  * @for p5
  * @requires core
  *
- * This is the main file for the Friendly Error System (FES). Here is a
+ * This is the main file for the Friendly Error System (FES), containing
+ * the core as well as miscellaneous functionality of the FES. Here is a
  * brief outline of the functions called in this system.
  *
- * The FES may be invoked by a call to either (1) _validateParameters,
- * (2) _friendlyFileLoadError, (3) _friendlyError, (4) helpForMisusedAtTopLevelCode,
- * or (5) _fesErrorMontitor.
+ * The FES may be invoked by a call to either
+ * (1) _validateParameters, (2) _friendlyFileLoadError, (3) _friendlyError,
+ * (4) helpForMisusedAtTopLevelCode, or (5) _fesErrorMontitor.
  *
- * _validateParameters is located in validate_params.js along with other code used
- * for parameter validation.
- * _friendlyFileLoadError is located in file_errors.js along with other code used for
- * dealing with file load errors.
- * Apart from this, there's also a file stacktrace.js, which contains the code to parse
- * the error stack, borrowed from https://github.com/stacktracejs/stacktrace.js
+ * _validateParameters is located in validate_params.js along with other code
+ * used for parameter validation.
+ * _friendlyFileLoadError is located in file_errors.js along with other code
+ * used for dealing with file load errors.
+ * Apart from this, there's also a file stacktrace.js, which contains the code
+ * to parse the error stack, borrowed from:
+ * https://github.com/stacktracejs/stacktrace.js
  *
- * This file contains the core as well as miscellaneous functionality of the FES.
- *
- * helpForMisusedAtTopLevelCode is called by this file on window load to check for use
- * of p5.js functions outside of setup() or draw()
- * Items 1-3 above are called by functions in the p5 library located in other files.
- *
- * _fesErrorMonitor can be called either by an error event, an unhandled rejection event
- * or it can be manually called in a catch block as follows:
- * try { someCode(); } catch(err) { p5._fesErrorMonitor(err); }
- * fesErrorMonitor is responsible for handling all kinds of errors that the browser may show.
- * It gives a simplified explanation for these. It currently works with some kinds of
- * ReferenceError, SyntaxError, and TypeError. The complete list of supported errors can be
- * found in browser_errors.js.
- *
- * _friendlyFileLoadError is called by the loadX() methods.
- * _friendlyError can be called by any function to offer a helpful error message.
- *
- * _validateParameters is called by functions in the p5.js API to help users ensure
- * ther are calling p5 function with the right parameter types. The property
- * disableFriendlyErrors = false can be set from a p5.js sketch to turn off parameter
- * checking. The call sequence from _validateParameters looks something like this:
- *
- * _validateParameters
- *   buildArgTypeCache
- *     addType
- *   lookupParamDoc
- *   scoreOverload
- *     testParamTypes
- *     testParamType
- *   getOverloadErrors
- *   _friendlyParamError
- *     ValidationError
- *     report
- *       friendlyWelcome
- *
- * The call sequences to _friendlyFileLoadError and _friendlyError are like this:
- * _friendlyFileLoadError
- *   report
- *
- * _friendlyError
- *   report
- *
- * The call sequence for _fesErrorMonitor roughly looks something like:
- * _fesErrorMonitor
- *   processStack
- *     printFriendlyError
- *   (if type of error is ReferenceError)
- *     _handleMisspelling
- *       computeEditDistance
- *       report
- *     report
- *     printFriendlyStack
- *   (if type of error is SyntaxError, TypeError, etc)
- *     report
- *     printFriendlyStack
- *
- * report() is the main function that prints directly to console with the output
- * of the error helper message. Note: friendlyWelcome() also prints to console directly.
+ * For more detailed information on the FES functions, including the call
+ * sequence of each function, please look at the FES Reference + Dev Notes:
+ * https://github.com/processing/p5.js/blob/main/contributor_docs/fes_reference_dev_notes.md
  */
 import p5 from '../main';
 import { translator } from '../internationalization';
@@ -176,8 +123,8 @@ if (typeof IS_MINIFIED !== 'undefined') {
    *
    * @method mapToReference
    * @private
-   * @param {String} message the words to be said
-   * @param {String} [func]    the name of the function to link
+   * @param {String}  message   the words to be said
+   * @param {String}  [func]    the name of function
    *
    * @returns {String}
    */
@@ -199,12 +146,13 @@ if (typeof IS_MINIFIED !== 'undefined') {
 
   /**
    * Prints out a fancy, colorful message to the console log
+   * Attaches Friendly Errors prefix [fes.pre] to the message.
    *
    * @method _report
    * @private
-   * @param  {String}               message the words to be said
-   * @param  {String}               [func]  the name of the function to link
-   * @param  {Number|String}        [color] CSS color string or error type
+   * @param  {String}          message  Message to be printed
+   * @param  {String}          [func]   Name of function
+   * @param  {Number|String}   [color]  CSS color code
    *
    * @return console logs
    */
@@ -242,16 +190,17 @@ if (typeof IS_MINIFIED !== 'undefined') {
    *
    * @method _friendlyError
    * @private
-   * @param  {Number} message message to be printed
-   * @param  {String} [method] name of method
-   * @param  {Number|String} [color]   CSS color string or error type
+   * @param  {String}         message   Message to be printed
+   * @param  {String}         [func]    Name of the function linked to error
+   * @param  {Number|String}  [color]   CSS color code
    */
-  p5._friendlyError = function(message, method, color) {
-    p5._report(message, method, color);
+  p5._friendlyError = function(message, func, color) {
+    p5._report(message, func, color);
   };
 
   /**
-   * This is called internally if there is a error with autoplay.
+   * This is called internally if there is an error with autoplay. Generates
+   * and prints a friendly error message [fes.autoplay].
    *
    * @method _friendlyAutoplayError
    * @private
@@ -265,11 +214,13 @@ if (typeof IS_MINIFIED !== 'undefined') {
   };
 
   /**
-   * An implementation of
-   * https://en.wikipedia.org/wiki/Wagner%E2%80%93Fischer_algorithm to
-   * compute the Levenshtein distance. It gives a measure of how dissimilar
-   * two strings are. If the "distance" between them is small enough, it is
+   * Measures dissimilarity between two strings by calculating
+   * the Levenshtein distance.
+   *
+   * If the "distance" between them is small enough, it is
    * reasonable to think that one is the misspelled version of the other.
+   *
+   * Specifically, this uses the Wagner–Fischer algorithm.
    * @method computeEditDistance
    * @private
    * @param {String} w1 the first word
@@ -316,12 +267,15 @@ if (typeof IS_MINIFIED !== 'undefined') {
   };
 
   /**
-   * checks if the various functions such as setup, draw, preload have been
-   * defined with capitalization mistakes
+   * Checks capitalization for user defined functions.
+   *
+   * Generates and prints a friendly error message using key:
+   * "fes.checkUserDefinedFns".
+   *
    * @method checkForUserDefinedFunctions
    * @private
-   * @param {*} context The current default context. It's set to window in
-   * "global mode" and to a p5 instance in "instance mode"
+   * @param {*} context   Current default context. Set to window in
+   *                      "global mode" and to a p5 instance in "instance mode"
    */
   const checkForUserDefinedFunctions = context => {
     if (p5.disableFriendlyErrors) return;
@@ -360,19 +314,17 @@ if (typeof IS_MINIFIED !== 'undefined') {
   };
 
   /**
-   * compares the the symbol caught in the ReferenceErrror to everything
-   * in misusedAtTopLevel ( all public p5 properties ). The use of
-   * misusedAtTopLevel here is for convenience as it was an array that was
-   * already defined when spelling check was implemented. For this particular
-   * use-case, it's a misnomer.
+   * Compares the symbol caught in the ReferenceErrror to everything in
+   * misusedAtTopLevel ( all public p5 properties ).
+   *
+   * Generates and prints a friendly error message using key: "fes.misspelling".
    *
    * @method handleMisspelling
    * @private
-   * @param {String} errSym the symbol to whose spelling to check
-   * @param {Error} error the ReferenceError object
+   * @param {String} errSym   Symbol to whose spelling to check
+   * @param {Error} error     ReferenceError object
    *
-   * @returns {Boolean} a boolean value indicating if this error was likely due
-   * to a mis-spelling
+   * @returns {Boolean} tell whether error was likely due to typo
    */
   const handleMisspelling = (errSym, error) => {
     if (!misusedAtTopLevelCode) {
@@ -422,7 +374,7 @@ if (typeof IS_MINIFIED !== 'undefined') {
       if (matchedSymbols.length === 1) {
         // To be used when there is only one closest match. The count parameter
         // allows i18n to pick between the keys "fes.misspelling" and
-        // "fes.misspelling__plural"
+        // "fes.misspelling_plural"
         msg = translator('fes.misspelling', {
           name: errSym,
           actualName: matchedSymbols[0].name,
@@ -464,8 +416,11 @@ if (typeof IS_MINIFIED !== 'undefined') {
   };
 
   /**
-   * prints a friendly stacktrace which only includes user-written functions
-   * and is easier for newcomers to understand
+   * Prints a friendly stacktrace for user-written functions for "global" errors
+   *
+   * Generates and prints a friendly error message using key:
+   * "fes.globalErrors.stackTop", "fes.globalErrors.stackSubseq".
+   *
    * @method printFriendlyStack
    * @private
    * @param {Array} friendlyStack
@@ -501,21 +456,28 @@ if (typeof IS_MINIFIED !== 'undefined') {
 
   /**
    * Takes a stacktrace array and filters out all frames that show internal p5
-   * details. It also uses this processed stack to figure out if the error
-   * error happened internally within the library, and if the error was due to
-   * a non-loadX() method being used in preload
-   * "Internally" here means that the error exact location of the error (the
-   * top of the stack) is a piece of code write in the p5.js library (which may
-   * or may not have been called from the user's sketch)
+   * details.
+   *
+   * Generates and prints a friendly error message using key:
+   * "fes.wrongPreload", "fes.libraryError".
+   *
+   * The processed stack is used to find whether the error happended internally
+   * within the library, and if the error was due to a non-loadX() method
+   * being used in preload.
+   *
+   * "Internally" here means that the exact location of the error (the top of
+   * the stack) is a piece of code write in the p5.js library (which may or
+   * may not have been called from the user's sketch).
    *
    * @method processStack
    * @private
    * @param {Error} error
    * @param {Array} stacktrace
    *
    * @returns {Array} An array with two elements, [isInternal, friendlyStack]
-   * isInternal: a boolean indicating if the error happened internally
-   * friendlyStack: the simplified stacktrace, with internal details filtered
+   *                 isInternal: a boolean value indicating whether the error
+   *                             happened internally
+   *                 friendlyStack: the filtered (simplified) stacktrace
    */
   const processStack = (error, stacktrace) => {
     // cannot process a stacktrace that doesn't exist
@@ -635,13 +597,17 @@ if (typeof IS_MINIFIED !== 'undefined') {
   };
 
   /**
-   * The main function for handling global errors. Called when an error
-   * happens and is responsible for detecting the type of error that
-   * has happened and showing the appropriate message
+   * Handles "global" errors that the browser catches.
+   *
+   * Called when an error event happens and detects the type of error.
+   *
+   * Generates and prints a friendly error message using key:
+   * "fes.globalErrors.syntax.[*]", "fes.globalErrors.reference.[*]",
+   * "fes.globalErrors.type.[*]".
    *
    * @method fesErrorMonitor
    * @private
-   * @param {*} e The object to extract error details from
+   * @param {*} e  Event object to extract error details from
    */
   const fesErrorMonitor = e => {
     if (p5.disableFriendlyErrors) return;
@@ -986,6 +952,12 @@ misusedAtTopLevelCode = null;
 const FAQ_URL =
   'https://github.com/processing/p5.js/wiki/p5.js-overview#why-cant-i-assign-variables-using-p5-functions-and-variables-before-setup';
 
+/**
+ * A helper function for populating misusedAtTopLevel list.
+ *
+ * @method defineMisusedAtTopLevelCode
+ * @private
+ */
 defineMisusedAtTopLevelCode = () => {
   const uniqueNamesFound = {};
 
@@ -1031,6 +1003,20 @@ defineMisusedAtTopLevelCode = () => {
   misusedAtTopLevelCode.sort((a, b) => b.name.length - a.name.length);
 };
 
+/**
+ * Detects browser level error event for p5 constants/functions used outside
+ * of setup() and draw().
+ *
+ * Generates and prints a friendly error message using key:
+ * "fes.misusedTopLevel".
+ *
+ * @method helpForMisusedAtTopLevelCode
+ * @private
+ * @param {Event} e       Error event
+ * @param {Boolean} log   false
+ *
+ * @returns {Boolean} true
+ */
 const helpForMisusedAtTopLevelCode = (e, log) => {
   if (!log) {
     log = console.log.bind(console);

src/core/friendly_errors/browser_errors.js

@@ -1,9 +1,6 @@
 /**
  * @for p5
  * @requires core
- *
- * This file contains the part of the FES responsible for dealing with
- * file load errors
  */
 import p5 from '../main';
 import { translator } from '../internationalization';
@@ -79,14 +76,16 @@ if (typeof IS_MINIFIED !== 'undefined') {
         };
     }
   };
-
   /**
-   * This is called internally if there is a error during file loading.
+   * Called internally if there is an error during file loading.
+   *
+   * Generates and prints a friendly error message using key:
+   * "fes.fileLoadError.[*]".
    *
    * @method _friendlyFileLoadError
    * @private
-   * @param  {Number} errorType
-   * @param  {String} filePath
+   * @param  {Number} errorType   Number of file load error type
+   * @param  {String} filePath    Path to file caused the error
    */
   p5._friendlyFileLoadError = function(errorType, filePath) {
     const { message, method } = fileLoadErrorCases(errorType, filePath);