8
0
Maciej Bukowski 6 лет назад
Родитель
Сommit
b6b061dd58

+ 15 - 13
packages/ckeditor5-watchdog/src/editorwatchdog.js

@@ -22,7 +22,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  */
 export default class EditorWatchdog extends Watchdog {
 	/**
-	 * @param {module:watchdog/watchdog~WatchdogConfig} [config] The watchdog plugin configuration.
+	 * @param {module:watchdog/editorwatchdog~EditorWatchdogConfig} [config] The watchdog plugin configuration.
 	 */
 	constructor( config = {} ) {
 		super( config );
@@ -155,7 +155,7 @@ export default class EditorWatchdog extends Watchdog {
 	 *
 	 * @param {HTMLElement|String|Object.<String|String>} [elementOrData]
 	 * @param {module:core/editor/editorconfig~EditorConfig} [config]
-	 * @param {Object} [context]
+	 * @param {Object} [context] A context for the editor.
 	 *
 	 * @returns {Promise}
 	 */
@@ -180,7 +180,7 @@ export default class EditorWatchdog extends Watchdog {
 
 		// Clone configuration because it might be shared within multiple watchdog instances. Otherwise,
 		// when an error occurs in one of these editors, the watchdog will restart all of them.
-		this._config = this._cloneConfig( config ) || {};
+		this._config = this._cloneEditorConfiguration( config ) || {};
 
 		this._config.context = context;
 
@@ -208,6 +208,9 @@ export default class EditorWatchdog extends Watchdog {
 		return this._destroy();
 	}
 
+	/**
+	 * @private
+	 */
 	async _destroy() {
 		this._stopErrorHandling();
 
@@ -283,7 +286,13 @@ export default class EditorWatchdog extends Watchdog {
 		return areConnectedThroughProperties( this._editor, error.context, this._excludedProps );
 	}
 
-	_cloneConfig( config ) {
+	/**
+	 * A function used to clone the editor configuration
+	 *
+	 * @private
+	 * @param {Object} config
+	 */
+	_cloneEditorConfiguration( config ) {
 		return cloneDeepWith( config, ( value, key ) => {
 			// Leave DOM references.
 			if ( isElement( value ) ) {
@@ -325,17 +334,10 @@ export default class EditorWatchdog extends Watchdog {
 }
 
 /**
- * The watchdog plugin configuration.
+ * The editor watchdog plugin configuration.
  *
- * @typedef {Object} WatchdogConfig
+ * @typedef {WatchdogConfig} EditorWatchdogConfig
  *
- * @property {Number} [crashNumberLimit=3] A threshold specifying the number of editor crashes
- * when the watchdog stops restarting the editor in case of errors.
- * After this limit is reached and the time between last errors is shorter than `minimumNonErrorTimePeriod`
- * the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
- * @property {Number} [minimumNonErrorTimePeriod=5000] An average amount of milliseconds between last editor errors
- * (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached
- * the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
  * @property {Number} [saveInterval=5000] A minimum number of milliseconds between saving editor data internally, (defaults to 5000).
  * Note that for large documents this might have an impact on the editor performance.
  */

+ 26 - 17
packages/ckeditor5-watchdog/src/watchdog.js

@@ -50,14 +50,14 @@ export default class Watchdog {
 		 */
 
 		/**
-		 * Specifies the state of the editor handled by the watchdog. The state can be one of the following values:
+		 * Specifies the state of the instance handled by the watchdog. The state can be one of the following values:
 		 *
-		 * * `initializing` - before the first initialization, and after crashes, before the editor is ready,
-		 * * `ready` - a state when a user can interact with the editor,
+		 * * `initializing` - before the first initialization, and after crashes, before the instance is ready,
+		 * * `ready` - a state when a user can interact with the instance,
 		 * * `crashed` - a state when an error occurs - it quickly changes to `initializing` or `crashedPermanently`
 		 * depending on how many and how frequency errors have been caught recently,
-		 * * `crashedPermanently` - a state when the watchdog stops reacting to errors and keeps the editor crashed,
-		 * * `destroyed` - a state when the editor is manually destroyed by the user after calling `watchdog.destroy()`
+		 * * `crashedPermanently` - a state when the watchdog stops reacting to errors and keeps the instance crashed,
+		 * * `destroyed` - a state when the instance is manually destroyed by the user after calling `watchdog.destroy()`
 		 *
 		 * @public
 		 * @observable
@@ -123,20 +123,29 @@ export default class Watchdog {
 	}
 
 	/**
-	 * @param {Function} creator
+	 * Sets the function that is responsible for the editor creation.
+	 *
+	 * @param {Function} creator A callback that takes source element or data as the first argument
+	 * and the editor configuration as the second argument and returns the promise that resolves
+	 * to the editor instance.
 	 */
 	setCreator( creator ) {
 		this._creator = creator;
 	}
 
 	/**
-	 * @param {Function} destructor
+	 * Sets the function that is responsible for the editor destruction.
+	 *
+	 * @param {Function} destructor A callback that takes the editor instance and returns the promise
+	 * to the destructing process.
 	 */
 	setDestructor( destructor ) {
 		this._destructor = destructor;
 	}
 
 	/**
+	 * Starts error handling by attaching global error handlers.
+	 *
 	 * @protected
 	 * @returns {Promise}
 	 */
@@ -146,6 +155,8 @@ export default class Watchdog {
 	}
 
 	/**
+	 * Stops error handling by detaching global error handlers.
+	 *
 	 * @protected
 	 * @returns {Promise}
 	 */
@@ -192,10 +203,10 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Checks whether the error should be handled.
+	 * Checks whether the error should be handled by the watchdog.
 	 *
 	 * @private
-	 * @param {Error} error Error
+	 * @param {Error} error An error that was caught by the error handling process.
 	 */
 	_shouldReactToError( error ) {
 		return (
@@ -215,7 +226,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Checks if the editor should be restarted or if it should be marked as crashed.
+	 * Checks if the watchdog should restart the underlying instance.
 	 */
 	_shouldRestart() {
 		if ( this.crashes.length <= this._crashNumberLimit ) {
@@ -245,13 +256,11 @@ mix( Watchdog, ObservableMixin );
  *
  * @typedef {Object} WatchdogConfig
  *
- * @property {Number} [crashNumberLimit=3] A threshold specifying the number of editor crashes
- * when the watchdog stops restarting the editor in case of errors.
+ * @property {Number} [crashNumberLimit=3] A threshold specifying the number of instance crashes
+ * when the watchdog stops restarting the instance in case of errors.
  * After this limit is reached and the time between last errors is shorter than `minimumNonErrorTimePeriod`
- * the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
- * @property {Number} [minimumNonErrorTimePeriod=5000] An average amount of milliseconds between last editor errors
+ * the watchdog changes its state to `crashedPermanently` and it stops restarting the instance. This prevents an infinite restart loop.
+ * @property {Number} [minimumNonErrorTimePeriod=5000] An average amount of milliseconds between last instance errors
  * (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached
- * the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
- * @property {Number} [saveInterval=5000] A minimum number of milliseconds between saving editor data internally, (defaults to 5000).
- * Note that for large documents this might have an impact on the editor performance.
+ * the watchdog changes its state to `crashedPermanently` and it stops restarting the instance. This prevents an infinite restart loop.
  */