Finished formatting and removed pretty names for survey plugins, talk to Josh about representation of data

packages/plugin-survey-html-form/src/index.ts

@@ -1,56 +1,76 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "survey-html-form",
+  version: version,
   parameters: {
     /** HTML formatted string containing all the input elements to display. Every element has to have its own distinctive name attribute. The <form> tag must not be included and is generated by the plugin. */
     html: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "HTML",
       default: null,
     },
     /** HTML formatted string to display at the top of the page above all the questions. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: null,
     },
     /** The text that appears on the button to finish the trial. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
     /** The HTML element ID of a form field to autofocus on. */
     autofocus: {
       type: ParameterType.STRING,
-      pretty_name: "Element ID to focus",
       default: "",
     },
     /** Retrieve the data as an array e.g. [{name: "INPUT_NAME", value: "INPUT_VALUE"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. */
     dataAsArray: {
       type: ParameterType.BOOL,
-      pretty_name: "Data As Array",
       default: false,
     },
     /** Setting this to true will enable browser auto-complete or auto-fill for the form. */
     autocomplete: {
       type: ParameterType.BOOL,
-      pretty_name: "Allow autocomplete",
       default: false,
     },
   },
+  data: {
+    /**  An object containing the response for each input. The object will have a separate key (variable) for the response to each input, with each variable being named after its corresponding input element. Each response is a string containing whatever the participant answered for this particular input. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      nested: {
+        identifier: {
+          type: ParameterType.STRING,
+        },
+        response: {
+          type:
+            ParameterType.STRING |
+            ParameterType.INT |
+            ParameterType.FLOAT |
+            ParameterType.BOOL |
+            ParameterType.OBJECT,
+        },
+      },
+    },
+    /** The response time in milliseconds for the participant to make a response. */
+    rt: {
+      type: ParameterType.INT,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **survey-html-form**
- *
- * jsPsych plugin for displaying free HTML forms and collecting responses from all input elements
  *
+ * The survey-html-form plugin displays a set of `<inputs>` from a HTML string. The type of input can be freely
+ * chosen, for a list of possible input types see the [MDN page on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
+ * The participant provides answers to the input fields.
  * @author Jan Simson
- * @see {@link https://www.jspsych.org/plugins/jspsych-survey-html-form/ survey-html-form plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/survey-html-form/ survey-html-form plugin documentation on jspsych.org}
  */
 class SurveyHtmlFormPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-survey-likert/src/index.ts

@@ -1,37 +1,35 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "survey-likert",
+  version: version,
   parameters: {
     /** Array containing one or more objects with parameters for the question(s) that should be shown on the page. */
     questions: {
       type: ParameterType.COMPLEX,
       array: true,
-      pretty_name: "Questions",
       nested: {
         /** Question prompt. */
         prompt: {
           type: ParameterType.HTML_STRING,
-          pretty_name: "Prompt",
           default: undefined,
         },
         /** Array of likert labels to display for this question. */
         labels: {
           type: ParameterType.STRING,
           array: true,
-          pretty_name: "Labels",
           default: undefined,
         },
         /** Whether or not a response to this question must be given in order to continue. */
         required: {
           type: ParameterType.BOOL,
-          pretty_name: "Required",
           default: false,
         },
         /** Name of the question in the trial data. If no name is given, the questions are named Q0, Q1, etc. */
         name: {
           type: ParameterType.STRING,
-          pretty_name: "Question Name",
           default: "",
         },
       },
@@ -39,45 +37,67 @@ const info = <const>{
     /** If true, the order of the questions in the 'questions' array will be randomized. */
     randomize_question_order: {
       type: ParameterType.BOOL,
-      pretty_name: "Randomize Question Order",
       default: false,
     },
     /** HTML-formatted string to display at top of the page above all of the questions. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: null,
     },
     /** Width of the likert scales in pixels. */
     scale_width: {
       type: ParameterType.INT,
-      pretty_name: "Scale width",
       default: null,
     },
     /** Label of the button to submit responses. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
     /** Setting this to true will enable browser auto-complete or auto-fill for the form. */
     autocomplete: {
       type: ParameterType.BOOL,
-      pretty_name: "Allow autocomplete",
       default: false,
     },
   },
+  data: {
+    /** An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in `Q0`, the second in `Q1`, and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the `name` parameter is defined for the question, then the response object will use the value of `name` as the key for each question. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      nested: {
+        identifier: {
+          type: ParameterType.STRING,
+        },
+        response: {
+          type:
+            ParameterType.STRING |
+            ParameterType.INT |
+            ParameterType.FLOAT |
+            ParameterType.BOOL |
+            ParameterType.OBJECT,
+        },
+      },
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** An array with the order of questions. For example `[2,0,1]` would indicate that the first question was `trial.questions[2]` (the third item in the `questions` parameter), the second question was `trial.questions[0]`, and the final question was `trial.questions[1]`. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    question_order: {
+      type: ParameterType.INT,
+      array: true,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **survey-likert**
+ * The survey-likert plugin displays a set of questions with Likert scale responses. The participant responds
- *
+ * by selecting a radio button.
- * jsPsych plugin for gathering responses to questions on a likert scale
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-survey-likert/ survey-likert plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/survey-likert/ survey-likert plugin documentation on jspsych.org}
  */
 class SurveyLikertPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-survey-multi-choice/src/index.ts

@@ -1,72 +1,110 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "survey-multi-choice",
+  version: version,
   parameters: {
-    /** Array containing one or more objects with parameters for the question(s) that should be shown on the page. */
+    /**
+     * An array of objects, each object represents a question that appears on the screen. Each object contains a prompt,
+     * options, required, and horizontal parameter that will be applied to the question. See examples below for further
+     * clarification.`prompt`: Type string, default value is *undefined*. The string is prompt/question that will be
+     * associated with a group of options (radio buttons). All questions will get presented on the same page (trial).
+     * `options`: Type array, defualt value is *undefined*. An array of strings. The array contains a set of options to
+     * display for an individual question.`required`: Type boolean, default value is null. The boolean value indicates
+     * if a question is required('true') or not ('false'), using the HTML5 `required` attribute. If this parameter is
+     * undefined, the question will be optional. `horizontal`:Type boolean, default value is false. If true, then the
+     * question is centered and the options are displayed horizontally. `name`: Name of the question. Used for storing
+     * data. If left undefined then default names (`Q0`, `Q1`, `...`) will be used for the questions.
+     */
     questions: {
       type: ParameterType.COMPLEX,
       array: true,
-      pretty_name: "Questions",
       nested: {
         /** Question prompt. */
         prompt: {
           type: ParameterType.HTML_STRING,
-          pretty_name: "Prompt",
           default: undefined,
         },
         /** Array of multiple choice options for this question. */
         options: {
           type: ParameterType.STRING,
-          pretty_name: "Options",
           array: true,
           default: undefined,
         },
         /** Whether or not a response to this question must be given in order to continue. */
         required: {
           type: ParameterType.BOOL,
-          pretty_name: "Required",
           default: false,
         },
         /** If true, then the question will be centered and options will be displayed horizontally. */
         horizontal: {
           type: ParameterType.BOOL,
-          pretty_name: "Horizontal",
           default: false,
         },
         /** Name of the question in the trial data. If no name is given, the questions are named Q0, Q1, etc. */
         name: {
           type: ParameterType.STRING,
-          pretty_name: "Question Name",
           default: "",
         },
       },
     },
-    /** If true, the order of the questions in the 'questions' array will be randomized. */
+    /**
+     * If true, the display order of `questions` is randomly determined at the start of the trial. In the data object,
+     * `Q0` will still refer to the first question in the array, regardless of where it was presented visually.
+     */
     randomize_question_order: {
       type: ParameterType.BOOL,
-      pretty_name: "Randomize Question Order",
       default: false,
     },
-    /** HTML-formatted string to display at top of the page above all of the questions. */
+    /** HTML formatted string to display at the top of the page above all the questions. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: null,
     },
-    /** Label of the button to submit responses. */
+    /** Label of the button. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
-    /** Setting this to true will enable browser auto-complete or auto-fill for the form. */
+    /**
+     * This determines whether or not all of the input elements on the page should allow autocomplete. Setting
+     * this to true will enable autocomplete or auto-fill for the form.
+     */
     autocomplete: {
       type: ParameterType.BOOL,
-      pretty_name: "Allow autocomplete",
       default: false,
     },
   },
+  data: {
+    /** An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in `Q0`, the second in `Q1`, and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the `name` parameter is defined for the question, then the response object will use the value of `name` as the key for each question. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      nested: {
+        identifier: {
+          type: ParameterType.STRING,
+        },
+        response: {
+          type:
+            ParameterType.STRING |
+            ParameterType.INT |
+            ParameterType.FLOAT |
+            ParameterType.BOOL |
+            ParameterType.OBJECT,
+        },
+      },
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** An array with the order of questions. For example `[2,0,1]` would indicate that the first question was `trial.questions[2]` (the third item in the `questions` parameter), the second question was `trial.questions[0]`, and the final question was `trial.questions[1]`. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    question_order: {
+      type: ParameterType.INT,
+      array: true,
+    },
+  },
 };
 
 type Info = typeof info;
@@ -74,10 +112,10 @@ type Info = typeof info;
 /**
  * **survey-multi-choice**
  *
- * jsPsych plugin for presenting multiple choice survey questions
+ * The survey-multi-choice plugin displays a set of questions with multiple choice response fields. The participant selects a single answer.
  *
  * @author Shane Martin
- * @see {@link https://www.jspsych.org/plugins/jspsych-survey-multi-choice/ survey-multi-choice plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/survey-multi-choice/ survey-multi-choice plugin documentation on jspsych.org}
  */
 class SurveyMultiChoicePlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-survey-multi-select/src/index.ts

@@ -1,88 +1,124 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "survey-multi-select",
+  version: version,
   parameters: {
-    /** Array containing one or more objects with parameters for the question(s) that should be shown on the page. */
+    /**
+     * An array of objects, each object represents a question that appears on the screen. Each object contains a prompt,
+     * options, required, and horizontal parameter that will be applied to the question. See examples below for further
+     * clarification.`prompt`: Type string, default value is *undefined*. The string is prompt/question that will be
+     * associated with a group of options (radio buttons). All questions will get presented on the same page (trial).
+     * `options`: Type array, defualt value is *undefined*. An array of strings. The array contains a set of options to
+     * display for an individual question.`required`: Type boolean, default value is null. The boolean value indicates
+     * if a question is required('true') or not ('false'), using the HTML5 `required` attribute. If this parameter is
+     * undefined, the question will be optional. `horizontal`:Type boolean, default value is false. If true, then the
+     * question is centered and the options are displayed horizontally. `name`: Name of the question. Used for storing
+     * data. If left undefined then default names (`Q0`, `Q1`, `...`) will be used for the questions.
+     */
     questions: {
       type: ParameterType.COMPLEX,
       array: true,
-      pretty_name: "Questions",
       nested: {
         /** Question prompt. */
         prompt: {
           type: ParameterType.HTML_STRING,
-          pretty_name: "Prompt",
           default: undefined,
         },
         /** Array of multiple select options for this question. */
         options: {
           type: ParameterType.STRING,
-          pretty_name: "Options",
           array: true,
           default: undefined,
         },
         /** If true, then the question will be centered and options will be displayed horizontally. */
         horizontal: {
           type: ParameterType.BOOL,
-          pretty_name: "Horizontal",
           default: false,
         },
         /** Whether or not a response to this question must be given in order to continue. */
         required: {
           type: ParameterType.BOOL,
-          pretty_name: "Required",
           default: false,
         },
         /** Name of the question in the trial data. If no name is given, the questions are named Q0, Q1, etc. */
         name: {
           type: ParameterType.STRING,
-          pretty_name: "Question Name",
           default: "",
         },
       },
     },
-    /** If true, the order of the questions in the 'questions' array will be randomized. */
+    /**
+     * If true, the display order of `questions` is randomly determined at the start of the trial. In the data
+     * object, `Q0` will still refer to the first question in the array, regardless of where it was presented
+     * visually.
+     */
     randomize_question_order: {
       type: ParameterType.BOOL,
-      pretty_name: "Randomize Question Order",
       default: false,
     },
-    /** HTML-formatted string to display at top of the page above all of the questions. */
+    /** HTML formatted string to display at the top of the page above all the questions. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: null,
     },
     /** Label of the button to submit responses. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
-    /** Message that will be displayed if one or more required questions is not answered. */
+    /** 'You must choose at least one response for this question' | Message to display if required response is not given. */
     required_message: {
       type: ParameterType.STRING,
-      pretty_name: "Required message",
       default: "You must choose at least one response for this question",
     },
-    /** Setting this to true will enable browser auto-complete or auto-fill for the form. */
+    /** This determines whether or not all of the input elements on the page should allow autocomplete.
+     * Setting this to true will enable autocomplete or auto-fill for the form. */
     autocomplete: {
       type: ParameterType.BOOL,
-      pretty_name: "Allow autocomplete",
       default: false,
     },
   },
+
+  data: {
+    /** An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in `Q0`, the second in `Q1`, and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the `name` parameter is defined for the question, then the response object will use the value of `name` as the key for each question. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      nested: {
+        identifier: {
+          type: ParameterType.STRING,
+        },
+        response: {
+          type:
+            ParameterType.STRING |
+            ParameterType.INT |
+            ParameterType.FLOAT |
+            ParameterType.BOOL |
+            ParameterType.OBJECT,
+        },
+      },
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** An array with the order of questions. For example `[2,0,1]` would indicate that the first question was `trial.questions[2]` (the third item in the `questions` parameter), the second question was `trial.questions[0]`, and the final question was `trial.questions[1]`. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    question_order: {
+      type: ParameterType.INT,
+      array: true,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **survey-multi-select**
+ * The survey-multi-select plugin displays a set of questions with multiple select response fields. The participant can
+ * select multiple answers.
  *
- * jsPsych plugin for presenting multiple choice survey questions with the ability to respond with more than one option
+ * @see {@link https://www.jspsych.org/latest/plugins/survey-multi-select/ survey-multi-select plugin documentation on jspsych.org}
- *
- * @see {@link https://www.jspsych.org/plugins/jspsych-survey-multi-select/ survey-multi-select plugin documentation on jspsych.org}
  */
 class SurveyMultiSelectPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-survey-text/src/index.ts

@@ -1,88 +1,123 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "survey-text",
+  version: version,
   parameters: {
+    /**
+     * An array of objects, each object represents a question that appears on the screen. Each object contains a prompt,
+     * options, required, and horizontal parameter that will be applied to the question. See examples below for further
+     * clarification.`prompt`: Type string, default value is *undefined*. The string is prompt/question that will be
+     * associated with a group of options (radio buttons). All questions will get presented on the same page (trial).
+     * `options`: Type array, defualt value is *undefined*. An array of strings. The array contains a set of options to
+     * display for an individual question.`required`: Type boolean, default value is null. The boolean value indicates
+     * if a question is required('true') or not ('false'), using the HTML5 `required` attribute. If this parameter is
+     * undefined, the question will be optional. `horizontal`:Type boolean, default value is false. If true, then the
+     * question is centered and the options are displayed horizontally. `name`: Name of the question. Used for storing
+     * data. If left undefined then default names (`Q0`, `Q1`, `...`) will be used for the questions.
+     */
     questions: {
       type: ParameterType.COMPLEX,
       array: true,
-      pretty_name: "Questions",
       default: undefined,
       nested: {
         /** Question prompt. */
         prompt: {
           type: ParameterType.HTML_STRING,
-          pretty_name: "Prompt",
           default: undefined,
         },
         /** Placeholder text in the response text box. */
         placeholder: {
           type: ParameterType.STRING,
-          pretty_name: "Placeholder",
           default: "",
         },
         /** The number of rows for the response text box. */
         rows: {
           type: ParameterType.INT,
-          pretty_name: "Rows",
           default: 1,
         },
         /** The number of columns for the response text box. */
         columns: {
           type: ParameterType.INT,
-          pretty_name: "Columns",
           default: 40,
         },
         /** Whether or not a response to this question must be given in order to continue. */
         required: {
           type: ParameterType.BOOL,
-          pretty_name: "Required",
           default: false,
         },
         /** Name of the question in the trial data. If no name is given, the questions are named Q0, Q1, etc. */
         name: {
           type: ParameterType.STRING,
-          pretty_name: "Question Name",
           default: "",
         },
       },
     },
-    /** If true, the order of the questions in the 'questions' array will be randomized. */
+    /**
+     * If true, the display order of `questions` is randomly determined at the start of the trial. In the data
+     * object, `Q0` will still refer to the first question in the array, regardless of where it was presented
+     * visually.
+     */
     randomize_question_order: {
       type: ParameterType.BOOL,
-      pretty_name: "Randomize Question Order",
       default: false,
     },
-    /** HTML-formatted string to display at top of the page above all of the questions. */
+    /** HTML formatted string to display at the top of the page above all the questions. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: null,
     },
     /** Label of the button to submit responses. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
     /** Setting this to true will enable browser auto-complete or auto-fill for the form. */
     autocomplete: {
       type: ParameterType.BOOL,
-      pretty_name: "Allow autocomplete",
       default: false,
     },
   },
+  data: {
+    /** An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in `Q0`, the second in `Q1`, and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the `name` parameter is defined for the question, then the response object will use the value of `name` as the key for each question. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      nested: {
+        identifier: {
+          type: ParameterType.STRING,
+        },
+        response: {
+          type:
+            ParameterType.STRING |
+            ParameterType.INT |
+            ParameterType.FLOAT |
+            ParameterType.BOOL |
+            ParameterType.OBJECT,
+        },
+      },
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** An array with the order of questions. For example `[2,0,1]` would indicate that the first question was `trial.questions[2]` (the third item in the `questions` parameter), the second question was `trial.questions[0]`, and the final question was `trial.questions[1]`. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    question_order: {
+      type: ParameterType.INT,
+      array: true,
+    },
+  },
 };
 
 type Info = typeof info;
 
 /**
- * **survey-text**
  *
- * jsPsych plugin for free text response survey questions
+ * The survey-text plugin displays a set of questions with free response text fields. The participant types in answers.
  *
  * @author Josh de Leeuw
- * @see {@link https://www.jspsych.org/plugins/jspsych-survey-text/ survey-text plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/survey-text/ survey-text plugin documentation on jspsych.org}
  */
 class SurveyTextPlugin implements JsPsychPlugin<Info> {
   static info = info;

packages/plugin-survey/src/index.ts

@@ -20,7 +20,6 @@ const info = <const>{
     survey_json: {
       type: ParameterType.OBJECT,
       default: {},
-      pretty_name: "Survey JSON object",
     },
     /**
      *
@@ -33,7 +32,6 @@ const info = <const>{
     survey_function: {
       type: ParameterType.FUNCTION,
       default: null,
-      pretty_name: "Survey function",
     },
     /**
      * A function that can be used to validate responses. This function is called whenever the SurveyJS `onValidateQuestion`
@@ -43,7 +41,6 @@ const info = <const>{
     validation_function: {
       type: ParameterType.FUNCTION,
       default: null,
-      pretty_name: "Validation function",
     },
   },
   data: {