Questions about which description to use when the doc seems less comp…

…lete than the jsDoc in the plugin (preload

packages/plugin-maxdiff/src/index.ts

@@ -1,53 +1,89 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "maxdiff",
+  version: version,
   parameters: {
-    /** Array containing the alternatives to be presented in the maxdiff table. */
+    /** An array of one or more alternatives of string type to fill the rows of the maxdiff table. If `required` is true,
+     * then the array must contain two or more alternatives, so that at least one can be selected for both the left
+     * and right columns.  */
     alternatives: {
       type: ParameterType.STRING,
-      pretty_name: "Alternatives",
       array: true,
       default: undefined,
     },
-    /** Array containing the labels to display for left and right response columns. */
+    /** An array with exactly two labels of string type to display as column headings (to the left and right of the
+     * alternatives) for responses on the criteria of interest. */
     labels: {
       type: ParameterType.STRING,
       array: true,
-      pretty_name: "Labels",
       default: undefined,
     },
-    /** If true, the order of the alternatives will be randomized. */
+    /** If true, the display order of `alternatives` is randomly determined at the start of the trial. */
     randomize_alternative_order: {
       type: ParameterType.BOOL,
-      pretty_name: "Randomize Alternative Order",
       default: false,
     },
-    /** String to display at top of the page. */
+    /** HTML formatted string to display at the top of the page above the maxdiff table. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: "",
     },
     /** Label of the button to submit response. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button Label",
       default: "Continue",
     },
-    /** Makes answering the alternative required. */
+    /** If true, prevents the user from submitting the response and proceeding until a radio button in both the left and right response columns has been selected. */
     required: {
       type: ParameterType.BOOL,
-      pretty_name: "Required",
       default: false,
     },
   },
+  data: {
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the maxdiff table first
+     * appears on the screen until the participant's response. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** An object with two keys, `left` and `right`, containing the labels (strings) corresponding to the left and right response
+     * columns. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions.  */
+    labels: {
+      type: ParameterType.COMPLEX,
+      parameters: {
+        left: {
+          type: ParameterType.STRING,
+        },
+        right: {
+          type: ParameterType.STRING,
+        },
+      },
+    },
+    /** An object with two keys, `left` and `right`, containing the alternatives selected on the left and right columns.
+     * This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      parameters: {
+        left: {
+          type: ParameterType.STRING,
+        },
+        right: {
+          type: ParameterType.STRING,
+        },
+      },
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * The maxdiff plugin displays a table with rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. The same alternative cannot be endorsed on both the left and right response columns (e.g. 'most' and 'least') simultaneously.
+ * The maxdiff plugin displays a table with rows of alternatives to be selected for two mutually-exclusive categories,
+ * typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant
+ * responds by selecting one radio button corresponding to an alternative in both the left and right response columns.
+ * The same alternative cannot be endorsed on both the left and right response columns (e.g. 'most' and 'least') simultaneously.
  *
  * @author Angus Hughes
  * @see {@link https://www.jspsych.org/latest/plugins/maxdiff/ maxdiff plugin documentation on jspsych.org}

packages/plugin-mirror-camera/src/index.ts

@@ -1,45 +1,57 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "mirror-camera",
+  version: version,
   parameters: {
-    /** HTML to render below the video */
+    /** HTML-formatted content to display below the camera feed. */
     prompt: {
       type: ParameterType.HTML_STRING,
       default: null,
     },
-    /** Label to show on continue button */
+    /** The label of the button to advance to the next trial. */
     button_label: {
       type: ParameterType.STRING,
       default: "Continue",
     },
-    /** Height of the video element */
+    /** The height of the video playback element. If left `null` then it will match the size of the recording. */
     height: {
       type: ParameterType.INT,
       default: null,
     },
-    /** Width of the video element */
+    /** The width of the video playback element. If left `null` then it will match the size of the recording. */
     width: {
       type: ParameterType.INT,
       default: null,
     },
-    /** Whether to flip the camera */
+    /**  Whether to mirror the video image. */
     mirror_camera: {
       type: ParameterType.BOOL,
       default: true,
     },
   },
+  data: {
+    /** The length of time the participant viewed the video playback. */
+    rt: {
+      type: ParameterType.INT,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **mirror-camera**
+ * This plugin shows a live feed of the participant's camera. It can be useful in experiments that need to record video in order to give the participant a chance to see what is in the view of the camera.
+ *
+ * You must initialize the camera using the [initialize-camera plugin](initialize-camera.md) prior to running this plugin.
  *
- * jsPsych plugin for showing a live stream from a camera
+ * !!! warning
+ *     When recording from a camera your experiment will need to be running over `https://` protocol. If you try to run the experiment locally using the `file://` protocol or over `http://` protocol you will not be able to access the camera because of [potential security problems](https://blog.mozilla.org/webrtc/camera-microphone-require-https-in-firefox-68/).
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-mirror-camera/ mirror-camera plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/mirror-camera/ mirror-camera plugin documentation on jspsych.org}
  */
 class MirrorCameraPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-preload/src/index.ts

@@ -1,28 +1,34 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "preload",
+  version: version,
   parameters: {
-    /** Whether or not to automatically preload any media files based on the timeline passed to jsPsych.run. */
+    /** If `true`, the plugin will preload any files that can be automatically preloaded based on the main experiment
+     * timeline that is passed to `jsPsych.run`. If `false`, any file(s) to be preloaded should be specified by passing
+     * a timeline array to the `trials` parameter and/or an array of file paths to the `images`, `audio`, and/or `video`
+     * parameters. Setting this parameter to `false` is useful when you plan to preload your files in smaller batches
+     * throughout the experiment. */
     auto_preload: {
       type: ParameterType.BOOL,
-      pretty_name: "Auto-preload",
       default: false,
     },
-    /** A timeline of trials to automatically preload. If one or more trial objects is provided in the timeline array, then the plugin will attempt to preload the media files used in the trial(s). */
+    /** An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to
+     * automatically preload stimuli files from a specific subset of the experiment. See [Creating an Experiment:
+     * The Timeline](../overview/timeline.md) for information on constructing timelines. */
     trials: {
       type: ParameterType.TIMELINE,
-      pretty_name: "Trials",
       default: [],
     },
     /**
-     * Array with one or more image files to load. This parameter is often used in cases where media files cannot#
+     * Array with one or more image files to load. This parameter is often used in cases where media files cannot
      * be automatically preloaded based on the timeline, e.g. because the media files are passed into an image plugin/parameter with
      * timeline variables or dynamic parameters, or because the image is embedded in an HTML string.
      */
     images: {
       type: ParameterType.STRING,
-      pretty_name: "Images",
       default: [],
       array: true,
     },
@@ -33,7 +39,6 @@ const info = <const>{
      */
     audio: {
       type: ParameterType.STRING,
-      pretty_name: "Audio",
       default: [],
       array: true,
     },
@@ -44,20 +49,17 @@ const info = <const>{
      */
     video: {
       type: ParameterType.STRING,
-      pretty_name: "Video",
       default: [],
       array: true,
     },
-    /** HTML-formatted message to be shown above the progress bar while the files are loading. */
+    /** HTML-formatted message to show above the progress bar while the files are loading. If `null`, then no message is shown. */
     message: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Message",
       default: null,
     },
-    /** Whether or not to show the loading progress bar. */
+    /** If `true`, a progress bar will be shown while the files are loading. If `false`, no progress bar is shown. */
     show_progress_bar: {
       type: ParameterType.BOOL,
-      pretty_name: "Show progress bar",
       default: true,
     },
     /**
@@ -67,13 +69,11 @@ const info = <const>{
      */
     continue_after_error: {
       type: ParameterType.BOOL,
-      pretty_name: "Continue after error",
       default: false,
     },
-    /** Error message to show on the page in case of any loading errors. This parameter is only relevant when continue_after_error is false. */
+    /** HTML-formatted message to be shown on the page after loading fails or times out. Only applies when `continue_after_error` is `false`.*/
     error_message: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Error message",
       default: "The experiment failed to load.",
     },
     /**
@@ -82,7 +82,6 @@ const info = <const>{
      */
     show_detailed_errors: {
       type: ParameterType.BOOL,
-      pretty_name: "Show detailed errors",
       default: false,
     },
     /**
@@ -92,33 +91,67 @@ const info = <const>{
      */
     max_load_time: {
       type: ParameterType.INT,
-      pretty_name: "Max load time",
       default: null,
     },
     /** Function to be called after a file fails to load. The function takes the file name as its only argument. */
     on_error: {
       type: ParameterType.FUNCTION,
-      pretty_name: "On error",
       default: null,
     },
     /** Function to be called after a file loads successfully. The function takes the file name as its only argument. */
     on_success: {
       type: ParameterType.FUNCTION,
-      pretty_name: "On success",
       default: null,
     },
   },
+  data: {
+    /**  If `true`, then all files loaded successfully within the `max_load_time`. If `false`, then one or
+     * more file requests returned a failure and/or the file loading did not complete within the `max_load_time` duration.*/
+    success: {
+      type: ParameterType.BOOL,
+    },
+    /** If `true`, then the files did not finish loading within the `max_load_time` duration.
+     * If `false`, then the file loading did not timeout. Note that when the preload trial does not timeout
+     * (`timeout: false`), it is still possible for loading to fail (`success: false`). This happens if
+     * one or more files fails to load and all file requests trigger either a success or failure event before
+     * the `max_load_time` duration. */
+    timeout: {
+      type: ParameterType.BOOL,
+    },
+    /** One or more image file paths that produced a loading failure before the trial ended. */
+    failed_images: {
+      type: ParameterType.STRING,
+      array: true,
+    },
+    /** One or more audio file paths that produced a loading failure before the trial ended. */
+    failed_audio: {
+      type: ParameterType.STRING,
+      array: true,
+    },
+    /** One or more video file paths that produced a loading failure before the trial ended. */
+    failed_video: {
+      type: ParameterType.STRING,
+      array: true,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **preload**
+ * This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are
+ * needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow.
+ * We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large
+ * and/or many media files. See the [Media Preloading page](../overview/media-preloading.md) for more information.
  *
- * jsPsych plugin for preloading image, audio, and video files
+ * The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error
+ * message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading
+ * when the `max_load_time` duration is reached, or (b) all file requests have responded with either a load or fail
+ * event, and one or more files has failed to load. The `continue_after_error` parameter determines whether the trial
+ * will stop with an error message or end (allowing the experiment to continue) when preloading is not successful.
  *
  * @author Becky Gilbert
- * @see {@link https://www.jspsych.org/plugins/jspsych-preload/ preload plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/preload/ preload plugin documentation on jspsych.org}
  */
 class PreloadPlugin implements JsPsychPlugin<Info> {
   static info = info;