some minor docs edits

docs/overview/dynamic-parameters.md

@@ -1,6 +1,10 @@
 # Dynamic parameters
 
-Most trial parameters can be functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial. This enables dynamic updating of the parameter based on data that a subject has generated or any other information that you do not know in advance.
+Most trial parameters can also be specified as functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, **when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial**. This enables dynamic updating of the parameter based on data that a subject has generated or any other information that you do not know in advance.
+
+## Examples
+
+### Providing Feedback
 
 Here is a sketch of how this functionality could be used to display feedback to a subject in the Flanker Task.
 
@@ -46,6 +50,8 @@ timeline.push(trial, feedback);
 
 ```
 
+### Randomizing a parameter value
+
 Here's an example of using a dynamic parameter to randomize the inter-trial interval (ITI) duration. This time, the dynamic parameter is created using a named function instead of an anonymous function.
 
 ```js
@@ -61,6 +67,8 @@ var trial = {
 }
 ```
 
+### Storing changing variables in the data
+
 The trial's `data` parameter can be also function, which is useful for when you want to save information to the data that can change during the experiment. For example, if you have a global variable called `current_difficulty` that tracks the difficulty level in an adaptive task, you can save the current value of this variable to the trial data like this:
 
 ```js
@@ -91,6 +99,8 @@ var trial = {
 }
 ```
 
+## Nested Parameters
+
 Dyanmic parameters work the same way with nested parameters, which are parameters that contain one or more sets of other parameters. For instance, many survey-* plugins have a `questions` parameter that is a nested parameter: it is an array that contains the parameters for one or more questions on the page. To make the `questions` parameter dynamic, you can use a function that returns the array with all of the parameters for each question:
 
 ```js
@@ -130,5 +140,8 @@ var trial = {
   ]
 }
 ```
+## When functions can't be used
 
 Note that if the plugin *expects* the value of a given parameter to be a function, then this function *will not* be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the `stimulus` parameter in the canvas-* plugins, the `mistake_fn` parameter in the cloze plugin, and the `stim_function` parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's `type` in the `plugin.info` section of the plugin file. If the parameter type is `jsPsych.plugins.parameterType.FUNCTION`, then this parameter must be a function and it will not be executed before the trial starts. 
+
+Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.

docs/overview/plugins.md

@@ -41,7 +41,7 @@ var image_trial = {
 
 Each plugin specifies its own set of parameters. Check the documentation for a plugin to see what parameters are available and what they do.
 
-In addition, there is a set of parameters that can be specified for any plugin:
+There is also a set of parameters that can be specified for any plugin:
 
 | Parameter      | Type     | Default Value           | Description                              |
 | -------------- | -------- | ----------------------- | ---------------------------------------- |
@@ -74,7 +74,7 @@ var trial = {
 
 Note the use of the data parameter to add a property `stimulus_type` with the value `congruent` and a property `target_direction` with the value `left`. Having these properties recorded directly in the data simplifies data analysis, making it easy to aggregate data by `stimulus_type` and/or `target_direction`.
 
-### The ITI (post_trial_gap) parameter
+### The post_trial_gap (ITI) parameter
 
 The default inter-trial interval (ITI) in jsPsych is 0 ms. This can be adjusted at the experiment-wide level by changing the `default_iti` parameter in `jsPsych.init()`.
 
@@ -119,7 +119,8 @@ The `on_finish` function can be useful to calculate new data properties that wer
 
 ```javascript
 // in addition to all of the standard data collected for this trial, 
-// the on_finish function adds a property called 'correct' which is either 'true' or 'false',
+// this on_finish function adds a property called 'correct' 
+// which is either 'true' or 'false'
 // depending on the response that was made
 var trial = {
   type: 'html-keyboard-response',
@@ -144,13 +145,15 @@ var trial = {
 
 The `on_load` callback function will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. This can be useful for changing various aspects of the page elements and their properties that would otherwise require modifying the plugin file.
 
-#### Sample use
 ```javascript
 var trial = {
   type: 'image-keyboard-response',
   stimulus: 'imgA.png',
   on_load: function() {
-    console.log('The trial just finished loading.');
+    // this will change the src attribute of the image after 500ms
+    setTimeout(function(){
+      document.querySelector('img').src = 'imgB.png'
+    }, 500);
   }
 };
 ```
@@ -204,13 +207,13 @@ The overall structure of the plugin is defined using a module JavaScript design
 
 The module, created by the `(function(){`  `})();` expressions, contains an object called `plugin`. The `plugin` object has two properties: `info` and `trial`. The `plugin` object is returned at the end of the module, which is what assigns the defined properties of `plugin` to `jsPsych['plugin-name']`.
 
-**plugin.info** 
+### plugin.info
 
 The plugin's `info` property is an object that contains all of the available parameters for the plugin. Each parameter name is a property, and the value is an object that includes a description of the parameter, the value's type (string, integer, etc.), and the default value. See some of the plugin files in the jsPsych plugins folder for examples.
 
-jsPsych allows most [plugin parameters to be dynamic](dynamic-parameters.md), which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that _shouldn't_ be evaluated before the trial starts, then you should make sure that the parameter type is 'FUNCTION'. This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the canvas-* plugins for examples.
+jsPsych allows most [plugin parameters to be dynamic](dynamic-parameters.md), which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that _shouldn't_ be evaluated before the trial starts, then you should make sure that the parameter type is `'FUNCTION'`. This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the `canvas-*` plugins for examples.
 
-**plugin.trial**
+### plugin.trial
 
 The plugin's `trial` property is a function that runs a single trial. There are two parameters that are passed into the trial method. The first, `display_element`, is the DOM element where jsPsych content is being rendered. This parameter will be an `HTMLElement`. Generally, you don't need to worry about this parameter being in the correct format, and can assume that it is an `HMTLElement` and use methods of that class. The second, `trial`, is an object containing all of the parameters specified in the corresponding TimelineNode. If you have specified all of your parameters in `plugin.info`, along with default values for each one, then the `trial` object will contain the default values for any parameters that were not specified in the trial's definition.
 
@@ -218,7 +221,7 @@ The only requirement for the `trial` method is that it calls `jsPsych.finishTria
 
 Of course, there are other things that you will probably want the plugin to do inside the `plugin.trial` function, besides just end. Here are some examples:
 
-**Changing the content of the display**
+### Changing the content of the display
 
 There are a few ways to change the content of the display. The `display_element` parameter of the trial method contains the DOM element for displaying content, so you can use various JavaScript methods for interaction with the display element. A common one is to change the `innerHTML`.
 
@@ -236,7 +239,7 @@ jsPsych doesn't clear the display before or after each trial, so it is often app
 display_element.innerHTML = '';
 ```
 
-**Writing data**
+### Writing data
 
 Plugins exist to collect data, so saving data is obviously a crucial thing to do. You can pass an object of data as the parameter to `jsPsych.finishTrial()`:
 
@@ -251,6 +254,6 @@ jsPsych.finishTrial(data);
 
 The data recorded will be that `correct` is `true` and that `rt` is `350`. Additional data for the trial will also be collected automatically by the jsPsych library.
 
-## The plugin template
+### The plugin template
 
 An empty plugin template is included in the `plugins/template` folder.

docs/overview/timeline.md

@@ -341,7 +341,7 @@ var face_name_procedure = {
 
 ## Looping timelines
 
-Any timeline can be looped using the `loop_function` option. The loop function should be a function that evaluates to `true` if the timeline should repeat, and `false` if the timeline should end. It receives a single parameter: the DataCollection object with all of the data from the trials executed in the last iteration of the timeline. The loop function will be evaluated after the timeline is completed.
+Any timeline can be looped using the `loop_function` option. The loop function should be a function that evaluates to `true` if the timeline should repeat, and `false` if the timeline should end. It receives a single parameter, named `data` by convention. This parameter will be the [DataCollection object](/core_library/jspsych-data/#datacollection) with all of the data from the trials executed in the last iteration of the timeline. The loop function will be evaluated after the timeline is completed.
 
 ```javascript
 var trial = {