viewport: set up autogenerated API docs in README (#14214)

WordPress · Mar 20, 2019 · d1f121a · d1f121a
1 parent ec0706f
commit d1f121a
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 19 deletions.
diff --git a/bin/update-readmes.js b/bin/update-readmes.js
@@ -31,7 +31,7 @@ const packages = [
 	'rich-text',
 	'shortcode',
 	//'url',
-	//'viewport',
+	'viewport',
 	//'wordcount',
 ];
 

diff --git a/packages/viewport/README.md b/packages/viewport/README.md
@@ -12,20 +12,20 @@ npm install @wordpress/viewport --save
 
 _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
 
-## Breakpoints
+## Usage
 
 The standard set of breakpoint thresholds is as follows:
 
-Name|Pixel Width
----|---
-`huge`|1440
-`wide`|1280
-`large`|960
-`medium`|782
-`small`|600
-`mobile`|480
+| Name     | Pixel Width |
+| -------- | ----------- |
+| `huge`   | 1440        |
+| `wide`   | 1280        |
+| `large`  | 960         |
+| `medium` | 782         |
+| `small`  | 600         |
+| `mobile` | 480         |
 
-## Data Module
+### Data Module
 
 The Viewport module registers itself under the `core/viewport` data namespace.
 
@@ -43,11 +43,24 @@ const isWideOrHuge = isViewportMatch( '>= wide' );
 //  const isWideOrHuge = isViewportMatch( 'wide' );
 ```
 
-## `ifViewportMatches` Higher-Order Component
+### Higher-Order Components
 
-If you are authoring a component which should only be shown under a specific viewport condition, you can leverage the `ifViewportMatches` higher-order component to achieve this requirement.
+This package provides a set of HOCs to author components whose behavior should vary depending on the viewport.
 
-Pass a viewport query to render the component only when the query is matched:
+<!-- START TOKEN(Autogenerated API docs) -->
+
+#### ifViewportMatches
+
+[src/index.js#L16-L16](src/index.js#L16-L16)
+
+Higher-order component creator, creating a new component which renders if
+the viewport query is satisfied.
+
+**Related**
+
+-   withViewportMatches
+
+**Usage**
 
 ```jsx
 function MyMobileComponent() {
@@ -57,11 +70,27 @@ function MyMobileComponent() {
 MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent );
 ```
 
-## `withViewportMatch` Higher-Order Component
+**Parameters**
+
+-   **query** `string`: Viewport query.
+
+**Returns**
+
+`Function`: Higher-order component.
+
+#### withViewportMatch
 
-If you are authoring a component which should vary its rendering behavior depending upon the matching viewport, you can leverage the `withViewportMatch` higher-order component to achieve this requirement.
+[src/index.js#L17-L17](src/index.js#L17-L17)
 
-Pass an object, where each key is a prop name and its value a viewport query. The component will be rendered with your prop(s) assigned with the result(s) of the query match:
+Higher-order component creator, creating a new component which renders with
+the given prop names, where the value passed to the underlying component is
+the result of the query assigned as the object's value.
+
+**Related**
+
+-   isViewportMatch
+
+**Usage**
 
 ```jsx
 function MyComponent( { isMobile } ) {
@@ -73,4 +102,15 @@ function MyComponent( { isMobile } ) {
 MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent );
 ```
 
+**Parameters**
+
+-   **queries** `Object`: Object of prop name to viewport query.
+
+**Returns**
+
+`Function`: Higher-order component.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/viewport/src/if-viewport-matches.js b/packages/viewport/src/if-viewport-matches.js
@@ -12,9 +12,19 @@ import withViewportMatch from './with-viewport-match';
  * Higher-order component creator, creating a new component which renders if
  * the viewport query is satisfied.
  *
+ * @see withViewportMatches
+ *
  * @param {string} query Viewport query.
  *
- * @see withViewportMatches
+ * @example
+ *
+ * ```jsx
+ * function MyMobileComponent() {
+ * 	return <div>I'm only rendered on mobile viewports!</div>;
+ * }
+ *
+ * MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent );
+ * ```
  *
  * @return {Function} Higher-order component.
  */

diff --git a/packages/viewport/src/with-viewport-match.js b/packages/viewport/src/with-viewport-match.js
@@ -14,9 +14,21 @@ import { withSelect } from '@wordpress/data';
  * the given prop names, where the value passed to the underlying component is
  * the result of the query assigned as the object's value.
  *
+ * @see isViewportMatch
+ *
  * @param {Object} queries  Object of prop name to viewport query.
  *
- * @see isViewportMatch
+ * @example
+ *
+ * ```jsx
+ * function MyComponent( { isMobile } ) {
+ * 	return (
+ * 		<div>Currently: { isMobile ? 'Mobile' : 'Not Mobile' }</div>
+ * 	);
+ * }
+ *
+ * MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent );
+ * ```
  *
  * @return {Function} Higher-order component.
  */