8
0
Просмотр исходного кода

Docs: Improved documentation for the notification plugin. Closes ckeditor/ckeditor5#1773.

Marek Lewandowski 6 лет назад
Родитель
Сommit
9b64c76390
1 измененных файлов с 53 добавлено и 51 удалено
  1. 53 51
      packages/ckeditor5-ui/src/notification/notification.js

+ 53 - 51
packages/ckeditor5-ui/src/notification/notification.js

@@ -14,11 +14,11 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 /**
 /**
  * The Notification plugin.
  * The Notification plugin.
  *
  *
- * This plugin sends few base types of notifications: `success`, `info` and `warning`. This notifications need to be
- * handled and displayed by plugin responsible for showing UI of the notifications. Using this plugin for dispatching
- * notifications makes possible to switch the notifications UI.
+ * This plugin sends a few types of notifications: `success`, `info` and `warning`. The notifications need to be
+ * handled and displayed by a plugin responsible for showing the UI of the notifications. Using this plugin for dispatching
+ * notifications makes it possible to switch the notifications UI.
  *
  *
- * Note that every unhandled and not stopped `warning` notification will be displayed as system alert.
+ * Note that every unhandled and not stopped `warning` notification will be displayed as a system alert.
  * See {@link module:ui/notification/notification~Notification#showWarning}.
  * See {@link module:ui/notification/notification~Notification#showWarning}.
  *
  *
  * @extends module:core/plugin~Plugin
  * @extends module:core/plugin~Plugin
@@ -35,33 +35,34 @@ export default class Notification extends Plugin {
 	 * @inheritDoc
 	 * @inheritDoc
 	 */
 	 */
 	init() {
 	init() {
-		// Each unhandled and not stopped `show:warning` event is displayed as system alert.
+		// Each unhandled and not stopped `show:warning` event is displayed as a system alert.
 		this.on( 'show:warning', ( evt, data ) => {
 		this.on( 'show:warning', ( evt, data ) => {
 			window.alert( data.message ); // eslint-disable-line no-alert
 			window.alert( data.message ); // eslint-disable-line no-alert
 		}, { priority: 'lowest' } );
 		}, { priority: 'lowest' } );
 	}
 	}
 
 
 	/**
 	/**
-	 * Shows success notification.
+	 * Shows a success notification.
 	 *
 	 *
-	 * At default it fires `show:success` event with given data but event namespace can be extended
-	 * by `data.namespace` option e.g.
+	 * By default, it fires the {@link #event:show:success `show:success` event} with the given `data`. The event namespace can be extended
+	 * using the `data.namespace` option. For example:
 	 *
 	 *
 	 * 		showSuccess( 'Image is uploaded.', {
 	 * 		showSuccess( 'Image is uploaded.', {
 	 * 			namespace: 'upload:image'
 	 * 			namespace: 'upload:image'
 	 * 		} );
 	 * 		} );
 	 *
 	 *
-	 * will fire `show:success:upload:image` event.
-	 * Title of the notification can be provided:
+	 * will fire the `show:success:upload:image` event.
+	 *
+	 * You can provide the title of the notification:
 	 *
 	 *
 	 *		showSuccess( 'Image is uploaded.', {
 	 *		showSuccess( 'Image is uploaded.', {
 	 *			title: 'Image upload success'
 	 *			title: 'Image upload success'
-	 *		});
+	 *		} );
 	 *
 	 *
-	 * @param {String} message Content of the notification.
+	 * @param {String} message The content of the notification.
 	 * @param {Object} [data={}] Additional data.
 	 * @param {Object} [data={}] Additional data.
 	 * @param {String} [data.namespace] Additional event namespace.
 	 * @param {String} [data.namespace] Additional event namespace.
-	 * @param {String} [data.title] Title of the notification.
+	 * @param {String} [data.title] The title of the notification.
 	 */
 	 */
 	showSuccess( message, data = {} ) {
 	showSuccess( message, data = {} ) {
 		this._showNotification( {
 		this._showNotification( {
@@ -73,26 +74,27 @@ export default class Notification extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Shows info notification.
+	 * Shows an information notification.
 	 *
 	 *
-	 * At default it fires `show:info` event with given data but event namespace can be extended
-	 * by `data.namespace` option e.g.
+	 * By default, it fires the {@link #event:show:info `show:info` event} with the given `data`. The event namespace can be extended
+	 * using the `data.namespace` option. For example:
 	 *
 	 *
 	 * 		showInfo( 'Editor is offline.', {
 	 * 		showInfo( 'Editor is offline.', {
 	 * 			namespace: 'editor:status'
 	 * 			namespace: 'editor:status'
 	 * 		} );
 	 * 		} );
 	 *
 	 *
-	 * will fire `show:info:editor:status` event.
-	 * Title of the notification can be provided:
+	 * will fire the `show:info:editor:status` event.
+	 *
+	 * You can provide the title of the notification:
 	 *
 	 *
 	 *		showInfo( 'Editor is offline.', {
 	 *		showInfo( 'Editor is offline.', {
 	 *			title: 'Network information'
 	 *			title: 'Network information'
-	 *		});
+	 *		} );
 	 *
 	 *
-	 * @param {String} message Content of the notification.
+	 * @param {String} message The content of the notification.
 	 * @param {Object} [data={}] Additional data.
 	 * @param {Object} [data={}] Additional data.
 	 * @param {String} [data.namespace] Additional event namespace.
 	 * @param {String} [data.namespace] Additional event namespace.
-	 * @param {String} [data.title] Title of the notification.
+	 * @param {String} [data.title] The title of the notification.
 	 */
 	 */
 	showInfo( message, data = {} ) {
 	showInfo( message, data = {} ) {
 		this._showNotification( {
 		this._showNotification( {
@@ -106,7 +108,7 @@ export default class Notification extends Plugin {
 	/**
 	/**
 	 * Shows a warning notification.
 	 * Shows a warning notification.
 	 *
 	 *
-	 * By default, it fires the {@link module:ui/notification/notification~Notification#event:show:warning `show:warning` event}
+	 * By default, it fires the {@link #event:show:warning `show:warning` event}
 	 * with the given `data`. The event namespace can be extended using the `data.namespace` option. For example:
 	 * with the given `data`. The event namespace can be extended using the `data.namespace` option. For example:
 	 *
 	 *
 	 * 		showWarning( 'Image upload error.', {
 	 * 		showWarning( 'Image upload error.', {
@@ -144,10 +146,10 @@ export default class Notification extends Plugin {
 	 * 			evt.stop();
 	 * 			evt.stop();
 	 * 		}, { priority: 'low' } );
 	 * 		}, { priority: 'low' } );
 	 *
 	 *
-	 * @param {String} message Content of the notification.
+	 * @param {String} message The content of the notification.
 	 * @param {Object} [data={}] Additional data.
 	 * @param {Object} [data={}] Additional data.
 	 * @param {String} [data.namespace] Additional event namespace.
 	 * @param {String} [data.namespace] Additional event namespace.
-	 * @param {String} [data.title] Title of the notification.
+	 * @param {String} [data.title] The title of the notification.
 	 */
 	 */
 	showWarning( message, data = {} ) {
 	showWarning( message, data = {} ) {
 		this._showNotification( {
 		this._showNotification( {
@@ -159,14 +161,14 @@ export default class Notification extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Fires `show` event with specified type, namespace and message.
+	 * Fires the `show` event with the specified type, namespace and message.
 	 *
 	 *
 	 * @private
 	 * @private
-	 * @param {Object} data Message data.
-	 * @param {String} data.message Content of the notification.
-	 * @param {'success'|'info'|'warning'} data.type Type of message.
+	 * @param {Object} data The message data.
+	 * @param {String} data.message The content of the notification.
+	 * @param {'success'|'info'|'warning'} data.type The type of the message.
 	 * @param {String} [data.namespace] Additional event namespace.
 	 * @param {String} [data.namespace] Additional event namespace.
-	 * @param {String} [data.title=''] Title of the notification.
+	 * @param {String} [data.title=''] The title of the notification.
 	 */
 	 */
 	_showNotification( data ) {
 	_showNotification( data ) {
 		const event = `show:${ data.type }` + ( data.namespace ? `:${ data.namespace }` : '' );
 		const event = `show:${ data.type }` + ( data.namespace ? `:${ data.namespace }` : '' );
@@ -179,45 +181,45 @@ export default class Notification extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Fired when one of `showSuccess`, `showInfo`, `showWarning` methods is called.
+	 * Fired when one of the `showSuccess()`, `showInfo()`, `showWarning()` methods is called.
 	 *
 	 *
 	 * @event show
 	 * @event show
-	 * @param {Object} data Notification data.
-	 * @param {String} data.message Content of the notification.
-	 * @param {String} data.title Title of the notification.
-	 * @param {'success'|'info'|'warning'} data.type Type of notification.
+	 * @param {Object} data The notification data.
+	 * @param {String} data.message The content of the notification.
+	 * @param {String} data.title The title of the notification.
+	 * @param {'success'|'info'|'warning'} data.type The type of the notification.
 	 */
 	 */
 
 
 	/**
 	/**
-	 * Fired when `showSuccess` method is called.
+	 * Fired when the `showSuccess()` method is called.
 	 *
 	 *
 	 * @event show:success
 	 * @event show:success
-	 * @param {Object} data Notification data.
-	 * @param {String} data.message Content of the notification.
-	 * @param {String} data.title Title of the notification.
-	 * @param {'success'} data.type Type of notification.
+	 * @param {Object} data The notification data.
+	 * @param {String} data.message The content of the notification.
+	 * @param {String} data.title The title of the notification.
+	 * @param {'success'} data.type The type of the notification.
 	 */
 	 */
 
 
 	/**
 	/**
-	 * Fired when `showInfo` method is called.
+	 * Fired when the `showInfo()` method is called.
 	 *
 	 *
 	 * @event show:info
 	 * @event show:info
-	 * @param {Object} data Notification data.
-	 * @param {String} data.message Content of the notification.
-	 * @param {String} data.title Title of the notification.
-	 * @param {'info'} data.type Type of notification.
+	 * @param {Object} data The notification data.
+	 * @param {String} data.message The content of the notification.
+	 * @param {String} data.title The title of the notification.
+	 * @param {'info'} data.type The type of the notification.
 	 */
 	 */
 
 
 	/**
 	/**
-	 * Fired when `showWarning` method is called.
+	 * Fired when the `showWarning()` method is called.
 	 *
 	 *
-	 * When this event won't be handled and stopped by `event.stop()` then data.message of this event will
-	 * be automatically displayed as system alert.
+	 * When this event is not handled or stopped by `event.stop()`, the `data.message` of this event will
+	 * be automatically displayed as a system alert.
 	 *
 	 *
 	 * @event show:warning
 	 * @event show:warning
-	 * @param {Object} data Notification data.
-	 * @param {String} data.message Content of the notification.
-	 * @param {String} data.title Title of the notification.
-	 * @param {'warning'} data.type Type of notification.
+	 * @param {Object} data The notification data.
+	 * @param {String} data.message The content of the notification.
+	 * @param {String} data.title The title of the notification.
+	 * @param {'warning'} data.type The type of the notification.
 	 */
 	 */
 }
 }