`autodoc`: extension param parser misses start parameters

[becky-gilbert]

I'm using autodoc on an extension package, and it's picking up my initialization parameters, but not my start parameters. I define the initialize and start parameters like this:

interface InitializeParameters {
  /**
   * Whether or not the pause/unpause should be controlled with a keyboard key press.
   * @default true
   */
  allow_key_response?: boolean;
  // ... more parameters ...
}

// Per-trial params are the same set of options as InitializeParameters.
// Any param provided here overrides the global default for that trial only.
type OnStartParameters = InitializeParameters;

class PauseExtension implements JsPsychExtension {
  static info: JsPsychExtensionInfo = {
    name: "extension-pause",
    version: version,
    // ... more static info ... 
  };

  initialize = (params: InitializeParameters): Promise<void> => {
    // ... code ... 
  };

  on_start = (params: OnStartParameters = {}): void => {
    // ... code ... 
  };

And here's the relevant bit of the generated doc:

<!-- jspsych-autodocs:init-parameters:start -->
### Initialization Parameters
Initialization parameters are set when calling `initJsPsych()`.

```js
initJsPsych({
  extensions: {
    { type: jsPsychExtensionExtensionPause, params: { ... } }
  }
})
```

| Parameter | Type | Default Value | Description |
| --------- | ---- | ------------- | ----------- |
| allow_key_response | boolean | `true` | Whether or not the pause/unpause should be controlled with a keyboard key press. |
   ... etc ...
<!-- jspsych-autodocs:init-parameters:end -->

<!-- jspsych-autodocs:trial-parameters:start -->
### Trial Parameters

Trial parameters are set when adding an extension to the trial object.

```js
var trial = {
  type: jsPsych...,
  extensions: [
    { type: jsPsychExtensionExtensionPause, params: { ... } }
  ]
}
```

| Parameter | Type | Default Value | Description |
| --------- | ---- | ------------- | ----------- |
<!-- jspsych-autodocs:trial-parameters:end -->

I'm assuming that my start parameters should be picked up by autodoc - is that right? Or have I done something weird with my start param argument type and/or on_start definition that's causing autodoc to miss it?

[jadeddelta]

@becky-gilbert ooo, this is an interesting one, the answer is that the autodoc package does not have any layers of indirection when searching for params, so it will only accept params of the regular object form as shown in your InitializeParameters, but won't recognize the statement in StartParameters. do you think this pattern of having categories of parameters equal to one another is common enough to add as potential behavior to address?

[becky-gilbert]

@jadeddelta glad to hear I hadn't done something terribly stupid! 😆

I would've thought that this a common pattern for extensions (i.e. parameters that can be set at a global/initialize level, and/or set on a per-trial basis), but I looked at the other extension pacakges in jsPsych and contrib and no one else does it this way. So probably no need to change anything in autodoc? Do I just need to write the start params using the same pattern as initialize? I.e.:

interface OnStartParameters {
  // ... parameters ...
}

on_start = (params: OnStartParameters = {}): void => {
    // ... code ... 
};

[jadeddelta]

@becky-gilbert if i'm understanding correctly, yes, precisely. you'll just have to copy the text defining the parameters in InitializeParameters into the OnStartParameters. you don't necessarily need to change the on_start function but since you've already made the swap for the interface, might as well.