Data: Document WPDataRegistry properties

[aduth]

Extracted from #16761

This pull request seeks to improve the type usage in the data module to use the custom WPDataRegistry type more consistently, and to add proper descriptions for the data registry properties.

Testing Instructions:

This impacts only JSDoc code comments and thus should have no impact on runtime operation.

[dsifford]

Just a few thoughts. I assume this is temporary until typescript checking makes its way here, so not super important.

In a nutshell: The types Object, Array, and Function = 😢 😭

[dsifford]

There's no way for editors to know how to interpret this without importing it in the file as its own typedef.

[aduth]

There's no way for editors to know how to interpret this without importing it in the file as its own typedef.

Hm, is this what the import is used for in your own pull requests? How does that work with @typedef (vs. your TypeScript definitions)?

[dsifford]

Precisely.

In javascript, in order to reference types that are defined elsewhere (be it in a typescript definition file, or as standard JSDoc), the types must first be imported in the referencing file as a @typedef. Once imported, you can freely reference the type throughout that file.

Otherwise the editor will not be able to provide type hints or "intellisense" (in VS editors)

[dsifford]

Type Object is not useful IMHO. I assume this is temporary until the typescript checking makes its way into this file, yes?

[aduth]

Type Object is not useful IMHO. I assume this is temporary until the typescript checking makes its way into this file, yes?

I'd say temporary, yes. I'm not really changing anything here aside from alignment and description. WPDataRegistry is the only type being changed throughout this pull request.

[dsifford]

Using this property as an example because it's the easiest one to do. IMHO, it would be better to do one of the following options since the type Function is not really helpful or descriptive.

Option 1

/**
 * @callback Subscriber Description of subscriber
 * @param {() => void} callback Description of callback parameter.
 * @return {void}
 */

Option 2

/**
 * @typedef {(callback: () => void) => void} Subscriber Description of subscriber
 */

And then use it on this line as...

/**
 * [...]
 * @prop {Subscriber} registerGenericStore Given a namespace key and settings
 *                                         object, registers a new generic store.
 * [...]
 */

---

I assume that this is also temporary though until typescript checking makes its way here. So not super important.

[aduth]

Are those syntaxes standard in JSDoc? It would be a good thing to detail in the documentation standards, I think.

In general, I agree with you. I didn't aim to change the types here, however.

[dsifford]

Yes.

I agree that the documentation standards should be combed through for accuracy and, ideally, these standards should be linted automatically. Pretty sure eslint-plugin-jsdoc should be able to do the brunt of this.

[dsifford]

I'd suggest making it the standard for this entire project (and all of WordPress, if possible) to use the tag @prop instead of @property to save on precious line lengths.

It'll help somewhat with the smushed descriptions.

[aduth]

It'll help somewhat with the smushed descriptions.

In some respect I appreciate the constraints to encourage being brief with the names and descriptions.

I don't have a strong feeling about @property vs. @prop, but it needs to be made in the documentation standards, which currently lists @prop as unsupported. A topic for a future JavaScript meeting, perhaps?