`autodoc` example parsing

[becky-gilbert]

I've just tried out the autodoc command with my new extension package, and it's working well - thanks!!

I noticed that it wasn't automatically parsing my example files and I had to use the start/end sentinels around relevant blocks. It looks like the example extractor will only pick up trial objects that include trial in the variable name (const trialPattern = /^[a-zA-Z_$]*[Tt]rial(_?\d+)?$/;), so it was failing to find anything in my example files that had variable names like fixation, test, countdown etc. I'm wondering if there was a reason for this restriction, or if the parser could pick up any objects in the examples that include a top-level extensions parameter? If you're open to that change, I can test it locally and open a PR.

Edit:

It might also be useful to do a recursive search for the extensions parameter, since the code block extractor missed my example code that had the trial object nested in a timeline node, like this:

// extractor missed this
const trial_restart_after_pause = {
  timeline: [
    {
      type: jsPsychHtmlButtonResponse,
      ... other params ...
      extensions: [ { type: jsPsychExtensionPause } ], // extension is nested
    },
  ],
};

[jadeddelta]

the regex match for trial text was a remnant of the implementation i used for the plugin example discovery, the idea I guess was to ensure that you could, using the smart extraction feature, omit certain trials like fixations or whatnot just to focus on the main plugin.. and at the same time include non-current-example trials that are necessary for the understanding of the plugin example, to be included.

though that reasoning is for plugins. for extensions, it makes a bit more sense to include something like that. ideally we also do want to maybe include the same logic, so something like first finding all extension mentions, and then doing a catchall for the plugin regex (with deduping). extensions being buried is one other thing, we maybe want to enforce top-level declarations in general just to ease the autodoc and produce a sort of standard for making jsPsych examples (so far we just have one example per file, attempt to use top-level declarations, don't use builder functions for inserting plugins into the timeline, etc etc).

if you wanna take a crack at it though just let me know (or not)! i won't work on the extension files for a bit in case you do decide to tackle it to avoid silly merge conflicts

[becky-gilbert]

the idea I guess was to ensure that you could, using the smart extraction feature, omit certain trials like fixations or whatnot just to focus on the main plugin.. and at the same time include non-current-example trials that are necessary for the understanding of the plugin example, to be included.

Makes perfect sense.

for extensions, it makes a bit more sense to include something like that. ideally we also do want to maybe include the same logic, so something like first finding all extension mentions, and then doing a catchall for the plugin regex (with deduping).

Ok, I'll take a crack at a PR for this.

extensions being buried is one other thing, we maybe want to enforce top-level declarations in general just to ease the autodoc and produce a sort of standard for making jsPsych examples (so far we just have one example per file, attempt to use top-level declarations, don't use builder functions for inserting plugins into the timeline, etc etc).

Yep that would probably be best. I ended up with the extension buried inside the timeline array of a timeline node because I was trying to demonstrate a specific case where it can be used with a looping timeline to repeat a trial if it was paused. But I think I can do the same thing by pulling the trial definition out of the timeline node array and then explicitly including the timeline node (which I think would otherwise be skipped?) by using the autodoc start/end flags. E.g. in my example file:

// jspsych-autodoc:start
const trial = {
  type: ...,
  extensions: [ { type: jsPsychExtensionPause } ],
};

const loop_node = {
  timeline: [trial]
  loop_function: ...
};
// jspsych-autodoc:end

Is that right?

[jadeddelta]

@becky-gilbert, sorry, I didn't see this one. yes, you would do just that, keep in mind that you can't have one and the other- if you use manual sentinel tags, you will have to go ahead and manually delineate every part of the file that you'd like to include.