`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