code cleanup and add documentation

packages/data/README.md

@@ -379,25 +379,57 @@ _Returns_
 
 <a name="RegistryConsumer" href="#RegistryConsumer">#</a> **RegistryConsumer**
 
-Undocumented declaration.
+A custom react Context consumer exposing the provided `registry` to
+children components. Used along with the RegistryProvider.
+
+You can read more about the react context api here:
+<https://reactjs.org/docs/context.html#contextprovider>
+
+_Usage_
+
+````js
+const {
+  RegistryProvider,
+  RegistryConsumer,
+  createRegistry
+} = wp.data;
+
+const registry = createRegistry( {} );
+
+const App = ( { props } ) => {
+  return <RegistryProvider value={ registry }>
+    <div>Hello There</div>
+    <RegistryConsumer>
+      { ( registry ) => (
+        <ComponentUsingRegistry
+        		{ ...props }
+        	  registry={ registry }
+      ) }
+    </RegistryConsumer>
+  </RegistryProvider>
+}
 
 <a name="RegistryProvider" href="#RegistryProvider">#</a> **RegistryProvider**
 
-Undocumented declaration.
+A custom Context provider for exposing the provided `registry` to children
+components via a consumer.
+
+See <a name="#RegistryConsumer">RegistryConsumer</a> documentation for
+example.
 
 <a name="select" href="#select">#</a> **select**
 
 Given the name of a registered store, returns an object of the store's selectors.
 The selector functions are been pre-bound to pass the current state automatically.
 As a consumer, you need only pass arguments of the selector, if applicable.
 
-_Usage_
+*Usage*
 
 ```js
 const { select } = wp.data;
 
 select( 'my-shop' ).getPrice( 'hammer' );
-```
+````
 
 _Parameters_
 
@@ -435,6 +467,91 @@ _Parameters_
 
 Undocumented declaration.
 
+<a name="useRegistry" href="#useRegistry">#</a> **useRegistry**
+
+A custom react hook exposing the registry context for use.
+
+This exposes the `registry` value provided via the
+<a href="#RegistryProvider">Registry Provider</a> to a component implementing
+this hook.
+
+It acts similarly to the `useContext` react hook.
+
+Note: Generally speaking, `useRegistry` is a low level hook that in most cases
+won't be needed for implementation. Most interactions with the wp.data api
+can be performed via the `useSelect` hook,  or the `withSelect` and
+`withDispatch` higher order components.
+
+_Usage_
+
+```js
+const {
+  RegistryProvider,
+  createRegistry,
+  useRegistry,
+} = wp.data
+
+const registry = createRegistry( {} );
+
+const SomeChildUsingRegistry = ( props ) => {
+  const registry = useRegistry( registry );
+  // ...logic implementing the registry in other react hooks.
+};
+
+
+const ParentProvidingRegistry = ( props ) => {
+  return <RegistryProvider value={ registry }>
+    <SomeChildUsingRegistry { ...props } />
+  </RegistryProvider>
+};
+```
+
+_Returns_
+
+-   `Function`: A custom react hook exposing the registry context value.
+
+<a name="useSelect" href="#useSelect">#</a> **useSelect**
+
+Custom react hook for retrieving props from registered selectors.
+
+In general, this custom React hook follows the
+[rules of hooks](https://reactjs.org/docs/hooks-rules.html).
+
+_Usage_
+
+```js
+const { useSelect } = wp.data;
+
+function HammerPriceDisplay( { currency } ) {
+  const price = useSelect( ( select ) => {
+    return select( 'my-shop' ).getPrice( 'hammer', currency )
+  }, [ currency ] );
+  return new Intl.NumberFormat( 'en-US', {
+    style: 'currency',
+    currency,
+  } ).format( price );
+}
+
+// Rendered in the application:
+// <HammerPriceDisplay currency="USD" />
+```
+
+In the above example, when `HammerPriceDisplay` is rendered into an
+application, the price will be retrieved from the store state using the
+`mapSelect` callback on `useSelect`. If the currency prop changes then
+any price in the state for that currency is retrieved. If the currency prop
+doesn't change and other props are passed in that do change, the price will
+not change because the dependency is just the currency.
+
+_Parameters_
+
+-   _\_mapSelect_ `Function`: Function called on every state change. The returned value is exposed to the component implementing this hook. The function receives the `registry.select` method on the first argument and the `registry` on the second argument.
+-   _deps_ `Array`: If provided, this memoizes the mapSelect so the same `mapSelect` is invoked on every state change unless the dependencies change.
+
+_Returns_
+
+-   `Function`: A custom react hook.
+
 <a name="withDispatch" href="#withDispatch">#</a> **withDispatch**
 
 Higher-order component used to add dispatch props using registered action creators.
@@ -516,7 +633,47 @@ _Returns_
 
 <a name="withSelect" href="#withSelect">#</a> **withSelect**
 
-Undocumented declaration.
+Higher-order component used to inject state-derived props using registered
+selectors.
+
+_Usage_
+
+```js
+function PriceDisplay( { price, currency } ) {
+	return new Intl.NumberFormat( 'en-US', {
+		style: 'currency',
+		currency,
+	} ).format( price );
+}
+
+const { withSelect } = wp.data;
+
+const HammerPriceDisplay = withSelect( ( select, ownProps ) => {
+	const { getPrice } = select( 'my-shop' );
+	const { currency } = ownProps;
+
+	return {
+		price: getPrice( 'hammer', currency ),
+	};
+} )( PriceDisplay );
+
+// Rendered in the application:
+//
+//  <HammerPriceDisplay currency="USD" />
+```
+
+In the above example, when `HammerPriceDisplay` is rendered into an
+application, it will pass the price into the underlying `PriceDisplay`
+component and update automatically if the price of a hammer ever changes in
+the store.
+
+_Parameters_
+
+-   _mapSelectToProps_ `Function`: Function called on every state change, expected to return object of props to merge with the component's own props.
+
+_Returns_
+
+-   `Component`: Enhanced component with merged state data props.
 
 
 <!-- END TOKEN(Autogenerated API docs) -->

packages/data/src/components/registry-provider/context.js

@@ -12,6 +12,43 @@ export const Context = createContext( defaultRegistry );
 
 const { Consumer, Provider } = Context;
 
+/**
+ * A custom react Context consumer exposing the provided `registry` to
+ * children components. Used along with the RegistryProvider.
+ *
+ * You can read more about the react context api here:
+ * https://reactjs.org/docs/context.html#contextprovider
+ *
+ * @example
+ * ```js
+ * const {
+ *   RegistryProvider,
+ *   RegistryConsumer,
+ *   createRegistry
+ * } = wp.data;
+ *
+ * const registry = createRegistry( {} );
+ *
+ * const App = ( { props } ) => {
+ *   return <RegistryProvider value={ registry }>
+ *     <div>Hello There</div>
+ *     <RegistryConsumer>
+ *       { ( registry ) => (
+ *         <ComponentUsingRegistry
+ *         		{ ...props }
+ *         	  registry={ registry }
+ *       ) }
+ *     </RegistryConsumer>
+ *   </RegistryProvider>
+ * }
+ */
 export const RegistryConsumer = Consumer;
 
+/**
+ * A custom Context provider for exposing the provided `registry` to children
+ * components via a consumer.
+ *
+ * See <a name="#RegistryConsumer">RegistryConsumer</a> documentation for
+ * example.
+ */
 export default Provider;

packages/data/src/components/registry-provider/use-registry.js

@@ -8,6 +8,45 @@ import { useContext } from '@wordpress/element';
  */
 import { Context } from './context';
 
+/**
+ * A custom react hook exposing the registry context for use.
+ *
+ * This exposes the `registry` value provided via the
+ * <a href="#RegistryProvider">Registry Provider</a> to a component implementing
+ * this hook.
+ *
+ * It acts similarly to the `useContext` react hook.
+ *
+ * Note: Generally speaking, `useRegistry` is a low level hook that in most cases
+ * won't be needed for implementation. Most interactions with the wp.data api
+ * can be performed via the `useSelect` hook,  or the `withSelect` and
+ * `withDispatch` higher order components.
+ *
+ * @example
+ * ```js
+ * const {
+ *   RegistryProvider,
+ *   createRegistry,
+ *   useRegistry,
+ * } = wp.data
+ *
+ * const registry = createRegistry( {} );
+ *
+ * const SomeChildUsingRegistry = ( props ) => {
+ *   const registry = useRegistry( registry );
+ *   // ...logic implementing the registry in other react hooks.
+ * };
+ *
+ *
+ * const ParentProvidingRegistry = ( props ) => {
+ *   return <RegistryProvider value={ registry }>
+ *     <SomeChildUsingRegistry { ...props } />
+ *   </RegistryProvider>
+ * };
+ * ```
+ *
+ * @return {Function}  A custom react hook exposing the registry context value.
+ */
 export default function useRegistry() {
 	return useContext( Context );
 }

packages/data/src/components/use-select/index.js

@@ -31,6 +31,49 @@ const useIsomorphicLayoutEffect =
 
 const renderQueue = createQueue();
 
+/**
+ * Custom react hook for retrieving props from registered selectors.
+ *
+ * In general, this custom React hook follows the
+ * [rules of hooks](https://reactjs.org/docs/hooks-rules.html).
+ *
+ * @param {Function} _mapSelect  Function called on every state change. The
+ *                               returned value is exposed to the component
+ *                               implementing this hook. The function receives
+ *                               the `registry.select` method on the first
+ *                               argument and the `registry` on the second
+ *                               argument.
+ * @param {Array}    deps        If provided, this memoizes the mapSelect so the
+ *                               same `mapSelect` is invoked on every state
+ *                               change unless the dependencies change.
+ *
+ * @example
+ * ```js
+ * const { useSelect } = wp.data;
+ *
+ * function HammerPriceDisplay( { currency } ) {
+ *   const price = useSelect( ( select ) => {
+ *     return select( 'my-shop' ).getPrice( 'hammer', currency )
+ *   }, [ currency ] );
+ *   return new Intl.NumberFormat( 'en-US', {
+ *     style: 'currency',
+ *     currency,
+ *   } ).format( price );
+ * }
+ *
+ * // Rendered in the application:
+ * // <HammerPriceDisplay currency="USD" />
+ * ```
+ *
+ * In the above example, when `HammerPriceDisplay` is rendered into an
+ * application, the price will be retrieved from the store state using the
+ * `mapSelect` callback on `useSelect`. If the currency prop changes then
+ * any price in the state for that currency is retrieved. If the currency prop
+ * doesn't change and other props are passed in that do change, the price will
+ * not change because the dependency is just the currency.
+ *
+ * @return {Function}  A custom react hook.
+ */
 export default function useSelect( _mapSelect, deps ) {
 	const mapSelect = useCallback( _mapSelect, deps );
 	const registry = useRegistry();