Data: Document WPDataRegistry properties (#16693)

* Data: Document WPDataRegistry properties

* Data: Use WPDataRegistry type where applicable

* Data: Fix WPDataRegistry typedef syntax

* Data: Bring WPDataRegistry into scope for typedef

packages/data/src/namespace-store/index.js

@@ -23,12 +23,18 @@ import metadataReducer from './metadata/reducer';
 import * as metadataSelectors from './metadata/selectors';
 import * as metadataActions from './metadata/actions';
 
+/**
+ * @typedef {import('../registry').WPDataRegistry} WPDataRegistry
+ */
+
 /**
  * Creates a namespace object with a store derived from the reducer given.
  *
- * @param {string} key              Identifying string used for namespace and redex dev tools.
- * @param {Object} options          Contains reducer, actions, selectors, and resolvers.
- * @param {Object} registry         Registry reference.
+ * @param {string}         key      Unique namespace identifier.
+ * @param {Object}         options  Registered store options, with properties
+ *                                  describing reducer, actions, selectors, and
+ *                                  resolvers.
+ * @param {WPDataRegistry} registry Registry reference.
  *
  * @return {Object} Store Object.
  */
@@ -102,10 +108,11 @@ export default function createNamespace( key, options, registry ) {
 /**
  * Creates a redux store for a namespace.
  *
- * @param {string} key      Part of the state shape to register the
- *                          selectors for.
- * @param {Object} options  Registered store options.
- * @param {Object} registry Registry reference, for resolver enhancer support.
+ * @param {string}         key      Unique namespace identifier.
+ * @param {Object}         options  Registered store options, with properties
+ *                                  describing reducer, actions, selectors, and
+ *                                  resolvers.
+ * @param {WPDataRegistry} registry Registry reference.
  *
  * @return {Object} Newly created redux store.
  */
@@ -143,15 +150,16 @@ function createReduxStore( key, options, registry ) {
 }
 
 /**
- * Maps selectors to a redux store.
+ * Maps selectors to a store.
  *
- * @param {Object} selectors  Selectors to register. Keys will be used as the
- *                            public facing API. Selectors will get passed the
- *                            state as first argument.
- * @param {Object} store      The redux store to which the selectors should be mapped.
- * @param {Object} registry   Registry reference.
+ * @param {Object}         selectors Selectors to register. Keys will be used as
+ *                                   the public facing API. Selectors will get
+ *                                   passed the state as first argument.
+ * @param {Object}         store     The store to which the selectors should be
+ *                                   mapped.
+ * @param {WPDataRegistry} registry  Registry reference.
  *
- * @return {Object}           Selectors mapped to the redux store provided.
+ * @return {Object} Selectors mapped to the provided store.
  */
 function mapSelectors( selectors, store, registry ) {
 	const createStateSelector = ( registeredSelector ) => {

packages/data/src/registry.js

@@ -15,13 +15,23 @@ import createCoreDataStore from './store';
 /**
  * An isolated orchestrator of store registrations.
  *
- * @typedef {WPDataRegistry}
+ * @typedef {Object} WPDataRegistry
  *
- * @property {Function} registerGenericStore
- * @property {Function} registerStore
- * @property {Function} subscribe
- * @property {Function} select
- * @property {Function} dispatch
+ * @property {Function} registerGenericStore Given a namespace key and settings
+ *                                           object, registers a new generic
+ *                                           store.
+ * @property {Function} registerStore        Given a namespace key and settings
+ *                                           object, registers a new namespace
+ *                                           store.
+ * @property {Function} subscribe            Given a function callback, invokes
+ *                                           the callback on any change to state
+ *                                           within any registered store.
+ * @property {Function} select               Given a namespace key, returns an
+ *                                           object of the  store's registered
+ *                                           selectors.
+ * @property {Function} dispatch             Given a namespace key, returns an
+ *                                           object of the store's registered
+ *                                           action dispatchers.
  */
 
 /**

packages/data/src/resolvers-cache-middleware.js

@@ -4,12 +4,14 @@
 import { get } from 'lodash';
 
 /**
- * creates a middleware handling resolvers cache invalidation.
+ * Creates a middleware handling resolvers cache invalidation.
  *
- * @param {Object} registry
- * @param {string} reducerKey
+ * @param {WPDataRegistry} registry   The registry reference for which to create
+ *                                    the middleware.
+ * @param {string}         reducerKey The namespace for which to create the
+ *                                    middleware.
  *
- * @return {function} middleware
+ * @return {Function} Middleware function.
  */
 const createResolversCacheMiddleware = ( registry, reducerKey ) => () => ( next ) => ( action ) => {
 	const resolvers = registry.select( 'core/data' ).getCachedResolvers( reducerKey );