Przeglądaj źródła

Docs: Docs improvements in the ContextualBalloon plugin.

Aleksander Nowodzinski 8 lat temu
rodzic
commit
e18b8483b2
1 zmienionych plików z 27 dodań i 23 usunięć
  1. 27 23
      packages/ckeditor5-ui/src/contextualballoon.js

+ 27 - 23
packages/ckeditor5-ui/src/contextualballoon.js

@@ -12,14 +12,18 @@ import BalloonPanelView from './panel/balloon/balloonpanelview';
 import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
- * Common contextual balloon of the Editor.
+ * Provides the common contextual balloon panel for the editor.
  *
- * This plugin is for reusing the same {module:ui/panel/balloon/balloonpanelview~BalloonPanelView} instance
- * for each contextual balloon panel in the editor. Also it makes possible to add multiple views to the same balloon.
- * Views are stored in the stack, last one in the stack is currently visible. When visible view will be removed from
- * the stack then previous view become visible, if there is no more view in the stack balloon will hide.
+ * This plugin allows reusing a single {module:ui/panel/balloon/balloonpanelview~BalloonPanelView} instance
+ * to display multiple contextual balloon panels in the editor.
  *
- * Using this plugin prevents of displaying more than one contextual balloon panel at the same time.
+ * Child views of such a panel are stored in the stack and the last one in the stack is visible. When the
+ * visible view is removed from the stack, the previous view becomes visible, etc. If there are no more
+ * views in the stack, the balloon panel will hide.
+ *
+ * It simplifies managing the views and helps
+ * avoid the unnecessary complexity of handling multiple {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
+ * instances in the editor.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -29,7 +33,7 @@ export default class ContextualBalloon extends Plugin {
 	 */
 	init() {
 		/**
-		 * Balloon panel view.
+		 * The common balloon panel view.
 		 *
 		 * @readonly
 		 * @member {module:ui/panel/balloon/balloonpanelview~BalloonPanelView} #view
@@ -37,8 +41,8 @@ export default class ContextualBalloon extends Plugin {
 		this.view = new BalloonPanelView();
 
 		/**
-		 * Stack of the views injected to the balloon. Last one in the stack is displayed
-		 * as content of {@link module:ui/contextualballoon~ContextualBalloon#view}.
+		 * Stack of the views injected into the balloon. Last one in the stack is displayed
+		 * as a content of {@link module:ui/contextualballoon~ContextualBalloon#view}.
 		 *
 		 * @private
 		 * @member {Map} #_stack
@@ -54,7 +58,8 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Returns configuration of currently visible view or `null` when there is no view in the stack.
+	 * Returns configuration of the currently visible view or `null` when there are no
+	 * views in the stack.
 	 *
 	 * @returns {module:ui/contextualballoon~ViewConfig|null}
 	 */
@@ -63,7 +68,7 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Returns `true` when given view is in the stack otherwise returns `false`.
+	 * Returns `true` when the given view is in the stack. Otherwise returns `false`.
 	 *
 	 * @param {module:ui/view~View} view
 	 * @returns {Boolean}
@@ -73,7 +78,7 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Adds view to the stack and makes it visible.
+	 * Adds a new view to the stack and makes it visible.
 	 *
 	 * @param {module:ui/contextualballoon~ViewConfig} data Configuration of the view.
 	 */
@@ -100,11 +105,11 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Removes given view from the stack. If removed view was visible
-	 * then the view before in the stack will be visible instead.
+	 * Removes the given view from the stack. If the removed view was visible,
+	 * then the view preceding it in the stack will become visible instead.
 	 * When there is no view in the stack then balloon will hide.
 	 *
-	 * @param {module:ui/view~View} view View which will be removed from the balloon.
+	 * @param {module:ui/view~View} view A view to be removed from the balloon.
 	 */
 	remove( view ) {
 		if ( !this.isViewInStack( view ) ) {
@@ -127,16 +132,14 @@ export default class ContextualBalloon extends Plugin {
 			// Next we need to check if there is other view in stack to show.
 			const last = Array.from( this._stack.values() ).pop();
 
-			// If it is.
+			// If it is some other view.
 			if ( last ) {
 				// Just show it.
 				this._show( last );
-			// Otherwise.
 			} else {
-				// Hide balloon panel.
+				// Hide the balloon panel.
 				this.view.hide();
 			}
-		// Otherwise.
 		} else {
 			// Just remove given view from the stack.
 			this._stack.delete( view );
@@ -144,7 +147,7 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Updates position of balloon panel according to position data
+	 * Updates the position of the balloon panel according to position data
 	 * of the first view in the stack.
 	 */
 	updatePosition() {
@@ -152,7 +155,8 @@ export default class ContextualBalloon extends Plugin {
 	}
 
 	/**
-	 * Sets view as a content of the balloon and attaches balloon using position options of the first view.
+	 * Sets the view as a content of the balloon and attaches balloon using position
+	 * options of the first view.
 	 *
 	 * @private
 	 * @param {module:ui/contextualballoon~ViewConfig} data Configuration of the view.
@@ -164,7 +168,7 @@ export default class ContextualBalloon extends Plugin {
 
 	/**
 	 * Returns position options of the first view in the stack.
-	 * This helps to keep balloon in the same position when view is changed.
+	 * This keeps the balloon in the same position when view is changed.
 	 *
 	 * @private
 	 * @returns {module:utils/dom/position~Options}
@@ -184,7 +188,7 @@ export default class ContextualBalloon extends Plugin {
 }
 
 /**
- * An object describing configuration of single view added to the balloon stack.
+ * An object describing configuration of a single view added to the balloon stack.
  *
  * @typedef {Object} module:ui/contextualballoon~ViewConfig
  *