From 59aa51d27b0b74fc9de2b5c956fa45f265643e15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 1 Mar 2019 19:38:43 +0100 Subject: [PATCH 1/3] Autogenerated docs and setup for deprecated --- packages/deprecated/README.md | 34 ++++++++++++++++++++++++++++++++ packages/deprecated/package.json | 6 ++++++ 2 files changed, 40 insertions(+) diff --git a/packages/deprecated/README.md b/packages/deprecated/README.md index 84c44f08d71d1..26ac5bf9586a9 100644 --- a/packages/deprecated/README.md +++ b/packages/deprecated/README.md @@ -43,4 +43,38 @@ function addDeprecationAlert( message, { version } ) { addAction( 'deprecated', 'my-plugin/add-deprecation-alert', addDeprecationAlert ); ``` +## API + + + +### default + +[src/index.js#L25-L64](src/index.js#L25-L64) + +Logs a message to notify developers about a deprecated feature. + +**Parameters** + +- **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. + +### logged + +[src/index.js#L12-L12](src/index.js#L12-L12) + +Object map tracking messages which have been logged, for use in ensuring a +message is only logged once. + +**Type** + +`Object` + + + +

Code is Poetry.

diff --git a/packages/deprecated/package.json b/packages/deprecated/package.json index 82c1876fb09ea..79e423239c848 100644 --- a/packages/deprecated/package.json +++ b/packages/deprecated/package.json @@ -24,7 +24,13 @@ "@babel/runtime": "^7.3.1", "@wordpress/hooks": "file:../hooks" }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, "publishConfig": { "access": "public" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 075c3d3905a3b36e20beafde0b9740e5100a6b01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 14:32:24 +0100 Subject: [PATCH 2/3] Use new script --- bin/update-readmes.js | 2 +- packages/deprecated/package.json | 6 ------ 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/bin/update-readmes.js b/bin/update-readmes.js index 6f1efc62ff5a8..675b828d44a26 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -14,7 +14,7 @@ const packages = [ 'compose', //'data', //'date', - //'deprecated', + 'deprecated', 'dom', 'dom-ready', 'e2e-test-utils', diff --git a/packages/deprecated/package.json b/packages/deprecated/package.json index 79e423239c848..82c1876fb09ea 100644 --- a/packages/deprecated/package.json +++ b/packages/deprecated/package.json @@ -24,13 +24,7 @@ "@babel/runtime": "^7.3.1", "@wordpress/hooks": "file:../hooks" }, - "devDependencies": { - "@wordpress/docgen": "file:../docgen" - }, "publishConfig": { "access": "public" - }, - "scripts": { - "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From fda46d71b48f3d2c7908c817838e4c7075685a0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 14:32:44 +0100 Subject: [PATCH 3/3] 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 26ac5bf9586a9..8f03c2ec0b3cd 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 10ebc176c8704..840c694994a17 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 {