From 6df8da558028809a50900ba989774d14ad084fcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Mar 2019 14:32:44 +0100
Subject: [PATCH] Update docs

---
 packages/deprecated/README.md    | 32 ++++++++++++++++----------------
 packages/deprecated/src/index.js | 14 ++++++++++++++
 2 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/packages/deprecated/README.md b/packages/deprecated/README.md
index 26ac5bf9586a91..8f03c2ec0b3cd1 100644
--- a/packages/deprecated/README.md
+++ b/packages/deprecated/README.md
@@ -12,21 +12,6 @@ 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
-
-```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.'
-```
-
 ## 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.
@@ -49,10 +34,25 @@ addAction( 'deprecated', 'my-plugin/add-deprecation-alert', addDeprecationAlert
 
 ### default
 
-[src/index.js#L25-L64](src/index.js#L25-L64)
+[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';
+
+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.'
+```
+
 **Parameters**
 
 -   **feature** `string`: Name of the deprecated feature.
diff --git a/packages/deprecated/src/index.js b/packages/deprecated/src/index.js
index 10ebc176c8704b..840c694994a170 100644
--- a/packages/deprecated/src/index.js
+++ b/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 {