Reference doc makes constructor parameters unclear

[kring]

This constructor has one required parameter, imageryProvider, and also a description that allows additional parameters to be specified. This is clear from looking at the source code, but not from the documentation. I was just talking to a user within AGI that tried a bunch of different variations before figuring out how to correctly call this constructor, and had similar problems with other APIs.

One easy improvement would be to list the names of the parameters. So change new ImageryLayer in the screenshot above to new ImageryLayer(imageryProvider, description). This should be done for methods, too, not just constructors.

[pjcozzi]

@shunter @kring this requires a change to the JDoc template, right?

[kring]

this requires a change to the JDoc template, right?

I don't know, but I can imagine this would be the case.

[mramato]

JSDoc (at least the latest version which @shunter is upgrading too) can support documentation of anonymous objects like this, so description would more clearly show up as a single object parameter with better documentation. I don't know all of the details, but it's worth looking into after we finish the upgrade.