Skip to content

Commit

Permalink
Fix type docs for Notices (#17206)
Browse files Browse the repository at this point in the history 
* Notices: Fix docs for optional params.

Fixes #17203

* Notices: Document missing properties.

Fixes #17203

* Notices: Rename `callback` to `onClick` for `WPNoticeAction`.

Fixes #17203
  • Loading branch information
@simono @gziolo
simono authored and gziolo committed Aug 30, 2019
1 parent c61bacc commit 1abf936
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 43 deletions.
25 changes: 13 additions & 12 deletions docs/designers-developers/developers/data/data-core-notices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ _Related_
_Parameters_

- _content_ `string`: Notice message.
- _options_ `?Object`: Optional notice options.
- _options_ `[Object]`: Optional notice options.

_Returns_

Expand All @@ -57,7 +57,7 @@ _Related_
_Parameters_

- _content_ `string`: Notice message.
- _options_ `?Object`: Optional notice options.
- _options_ `[Object]`: Optional notice options.

_Returns_

Expand All @@ -69,14 +69,15 @@ Yields action objects used in signalling that a notice is to be created.

_Parameters_

- _status_ `?string`: Notice status. Defaults to `info`.
- _status_ `[string]`: Notice status.
- _content_ `string`: Notice message.
- _options_ `?Object`: Notice options.
- _options.context_ `?string`: Context under which to group notice.
- _options.id_ `?string`: Identifier for notice. Automatically assigned if not specified.
- _options.isDismissible_ `?boolean`: Whether the notice can be dismissed by user. Defaults to `true`.
- _options.speak_ `?boolean`: Whether the notice content should be announced to screen readers. Defaults to `true`.
- _options.actions_ `?Array<WPNoticeAction>`: User actions to be presented with notice.
- _options_ `[Object]`: Notice options.
- _options.context_ `[string]`: Context under which to group notice.
- _options.id_ `[string]`: Identifier for notice. Automatically assigned if not specified.
- _options.isDismissible_ `[boolean]`: Whether the notice can be dismissed by user.
- _options.type_ `[string]`: Type of notice, one of `default`, or `snackbar`.
- _options.speak_ `[boolean]`: Whether the notice content should be announced to screen readers.
- _options.actions_ `[Array<WPNoticeAction>]`: User actions to be presented with notice.

<a name="createSuccessNotice" href="#createSuccessNotice">#</a> **createSuccessNotice**

Expand All @@ -90,7 +91,7 @@ _Related_
_Parameters_

- _content_ `string`: Notice message.
- _options_ `?Object`: Optional notice options.
- _options_ `[Object]`: Optional notice options.

_Returns_

Expand All @@ -108,7 +109,7 @@ _Related_
_Parameters_

- _content_ `string`: Notice message.
- _options_ `?Object`: Optional notice options.
- _options_ `[Object]`: Optional notice options.

_Returns_

Expand All @@ -121,7 +122,7 @@ Returns an action object used in signalling that a notice is to be removed.
_Parameters_

- _id_ `string`: Notice unique identifier.
- _context_ `?string`: Optional context (grouping) in which the notice is intended to appear. Defaults to default context.
- _context_ `[string]`: Optional context (grouping) in which the notice is intended to appear. Defaults to default context.

_Returns_

Expand Down
59 changes: 29 additions & 30 deletions packages/notices/src/store/actions.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,25 +11,24 @@ import { DEFAULT_CONTEXT, DEFAULT_STATUS } from './constants';
/**
* Yields action objects used in signalling that a notice is to be created.
*
* @param {?string} status Notice status.
* Defaults to `info`.
* @param {string} content Notice message.
* @param {?Object} options Notice options.
* @param {?string} options.context Context under which to
* group notice.
* @param {?string} options.id Identifier for notice.
* Automatically assigned
* if not specified.
* @param {?boolean} options.isDismissible Whether the notice can
* be dismissed by user.
* Defaults to `true`.
* @param {?boolean} options.speak Whether the notice
* content should be
* announced to screen
* readers. Defaults to
* `true`.
* @param {?Array<WPNoticeAction>} options.actions User actions to be
* presented with notice.
* @param {string} [status='info'] Notice status.
* @param {string} content Notice message.
* @param {Object} [options] Notice options.
* @param {string} [options.context='global'] Context under which to
* group notice.
* @param {string} [options.id] Identifier for notice.
* Automatically assigned
* if not specified.
* @param {boolean} [options.isDismissible=true] Whether the notice can
* be dismissed by user.
* @param {string} [options.type='default'] Type of notice, one of
* `default`, or `snackbar`.
* @param {boolean} [options.speak=true] Whether the notice
* content should be
* announced to screen
* readers.
* @param {Array<WPNoticeAction>} [options.actions] User actions to be
* presented with notice.
*/
export function* createNotice( status = DEFAULT_STATUS, content, options = {} ) {
const {
Expand Down Expand Up @@ -76,8 +75,8 @@ export function* createNotice( status = DEFAULT_STATUS, content, options = {} )
*
* @see createNotice
*
* @param {string} content Notice message.
* @param {?Object} options Optional notice options.
* @param {string} content Notice message.
* @param {Object} [options] Optional notice options.
*
* @return {Object} Action object.
*/
Expand All @@ -91,8 +90,8 @@ export function createSuccessNotice( content, options ) {
*
* @see createNotice
*
* @param {string} content Notice message.
* @param {?Object} options Optional notice options.
* @param {string} content Notice message.
* @param {Object} [options] Optional notice options.
*
* @return {Object} Action object.
*/
Expand All @@ -106,8 +105,8 @@ export function createInfoNotice( content, options ) {
*
* @see createNotice
*
* @param {string} content Notice message.
* @param {?Object} options Optional notice options.
* @param {string} content Notice message.
* @param {Object} [options] Optional notice options.
*
* @return {Object} Action object.
*/
Expand All @@ -121,8 +120,8 @@ export function createErrorNotice( content, options ) {
*
* @see createNotice
*
* @param {string} content Notice message.
* @param {?Object} options Optional notice options.
* @param {string} content Notice message.
* @param {Object} [options] Optional notice options.
*
* @return {Object} Action object.
*/
Expand All @@ -133,9 +132,9 @@ export function createWarningNotice( content, options ) {
/**
* Returns an action object used in signalling that a notice is to be removed.
*
* @param {string} id Notice unique identifier.
* @param {?string} context Optional context (grouping) in which the notice is
* intended to appear. Defaults to default context.
* @param {string} id Notice unique identifier.
* @param {string} [context='global'] Optional context (grouping) in which the notice is
* intended to appear. Defaults to default context.
*
* @return {Object} Action object.
*/
Expand Down
7 changes: 6 additions & 1 deletion packages/notices/src/store/selectors.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ const DEFAULT_NOTICES = [];
* removal without notice.
* @property {boolean} isDismissible Whether the notice can be dismissed by
* user. Defaults to `true`.
* @property {string} type Type of notice, one of `default`,
* or `snackbar`. Defaults to `default`.
* @property {boolean} speak Whether the notice content should be
* announced to screen readers. Defaults to
* `true`.
* @property {WPNoticeAction[]} actions User actions to present with notice.
*
*/
Expand All @@ -39,7 +44,7 @@ const DEFAULT_NOTICES = [];
* @property {string} label Message to use as action label.
* @property {?string} url Optional URL of resource if action incurs
* browser navigation.
* @property {?Function} callback Optional function to invoke when action is
* @property {?Function} onClick Optional function to invoke when action is
* triggered by user.
*
*/
Expand Down

0 comments on commit 1abf936

Please sign in to comment.