deprecated: set up auto-generated API docs (#14275)

bin/update-readmes.js

@@ -15,7 +15,7 @@ const packages = [
 	'compose',
 	//'data',
 	//'date',
-	//'deprecated',
+	'deprecated',
 	'dom',
 	'dom-ready',
 	'e2e-test-utils',

packages/deprecated/README.md

@@ -12,7 +12,33 @@ npm install @wordpress/deprecated --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)._
 
-## Usage
+## Hook
+
+The `deprecated` action is fired with three parameters: the name of the deprecated feature, the options object passed to deprecated, and the message sent to the console.
+
+_Example:_
+
+```js
+import { addAction } from '@wordpress/hooks';
+
+function addDeprecationAlert( message, { version } ) {
+	alert( `Deprecation: ${ message }. Version: ${ version }` );	
+}
+
+addAction( 'deprecated', 'my-plugin/add-deprecation-alert', addDeprecationAlert );
+```
+
+## API
+
+<!-- START TOKEN(Autogenerated API docs) -->
+
+### default
+
+[src/index.js#L39-L78](src/index.js#L39-L78)
+
+Logs a message to notify developers about a deprecated feature.
+
+**Usage**
 
 ```js
 import deprecated from '@wordpress/deprecated';
@@ -27,20 +53,28 @@ deprecated( 'Eating meat', {
 // Logs: 'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
 ```
 
-## Hook
+**Parameters**
 
-The `deprecated` action is fired with three parameters: the name of the deprecated feature, the options object passed to deprecated, and the message sent to the console.
+-   **feature** `string`: Name of the deprecated feature.
+-   **options** `?Object`: Personalisation options
+-   **options.version** `?string`: Version in which the feature will be removed.
+-   **options.alternative** `?string`: Feature to use instead
+-   **options.plugin** `?string`: Plugin name if it's a plugin feature
+-   **options.link** `?string`: Link to documentation
+-   **options.hint** `?string`: Additional message to help transition away from the deprecated feature.
 
-_Example:_
+### logged
 
-```js
-import { addAction } from '@wordpress/hooks';
+[src/index.js#L12-L12](src/index.js#L12-L12)
 
-function addDeprecationAlert( message, { version } ) {
-	alert( `Deprecation: ${ message }. Version: ${ version }` );	
-}
+Object map tracking messages which have been logged, for use in ensuring a
+message is only logged once.
 
-addAction( 'deprecated', 'my-plugin/add-deprecation-alert', addDeprecationAlert );
-```
+**Type**
+
+`Object` 
+
+
+<!-- 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>

packages/deprecated/src/index.js

@@ -21,6 +21,20 @@ export const logged = Object.create( null );
  * @param {?string} options.plugin      Plugin name if it's a plugin feature
  * @param {?string} options.link        Link to documentation
  * @param {?string} options.hint        Additional message to help transition away from the deprecated feature.
+ *
+ * @example
+ * ```js
+ * import deprecated from '@wordpress/deprecated';
+ *
+ * deprecated( 'Eating meat', {
+ * 	version: 'the future',
+ * 	alternative: 'vegetables',
+ * 	plugin: 'the earth',
+ * 	hint: 'You may find it beneficial to transition gradually.',
+ * } );
+ *
+ * // Logs: 'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
+ * ```
  */
 export default function deprecated( feature, options = {} ) {
 	const {