Merge branch 'stable'

README.md

@@ -9,11 +9,11 @@ CKEditor 5 watchdog feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-watchdog/status.svg)](https://david-dm.org/ckeditor/ckeditor5-watchdog)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-watchdog/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-watchdog?type=dev)
 
-This package implements the watchdog feature for CKEditor 5.
+This package implements the watchdog feature for CKEditor 5. It keeps a CKEditor 5 rich-text editor instance running.
 
 ## Documentation
 
-See the [`@ckeditor/ckeditor5-watchdog` package](https://ckeditor.com/docs/ckeditor5/latest/api/watchdog.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+See the [`@ckeditor/ckeditor5-watchdog` package](https://ckeditor.com/docs/ckeditor5/latest/api/watchdog.html) page as well as the [Watchdog feature guide](https://ckeditor.com/docs/ckeditor5/latest/features/watchdog.html) in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
 
 ## License
 

docs/api/watchdog.md

@@ -6,7 +6,7 @@ category: api-reference
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-watchdog.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog)
 
-This package implements the watchdog feature for CKEditor 5.
+This package implements the watchdog feature for CKEditor 5. It keeps a CKEditor 5 rich-text editor instance running.
 
 ## Documentation
 

docs/features/watchdog.md

@@ -5,16 +5,16 @@ category: features
 
 # Watchdog
 
-Every non trivial piece of software has bugs. Despite our high quality standards like 100% code coverage, regression testing and manual tests before every release, CKEditor 5 is not free of bugs. Neither is the browser used by the user, your application in which CKEditor 5 is integrate, or any 3rd party addons that you used.
+Every non-trivial piece of software has bugs. Despite our high quality standards like 100% code coverage, regression testing and manual tests before every release, CKEditor 5 is not free of bugs. Neither is the browser used by the user, your application in which CKEditor 5 is integrated, or any third-party addons that you used.
 
-In order to limit the effect of an editor crash on the user experience, you can automatically restart the editor with the content saved just before the crash.
+In order to limit the effect of an editor crash on the user experience, you can automatically restart the WYSIWYG editor with the content saved just before the crash.
 
-The {@link module:watchdog/watchdog~Watchdog} util allows you to do that exactly. It ensures that an editor instance is running, despite a potential crash. It works by detecting that an editor crashed, destroying it and automatically creating a new instance of that editor with the content of the previous editor.
+The {@link module:watchdog/watchdog~Watchdog} utility allows you to do exactly that. It ensures that an editor instance is running, despite a potential crash. It works by detecting that an editor crashed, destroying it, and automatically creating a new instance of that editor with the content of the previous editor.
 
 ## Usage
 
 <info-box>
-	Note: watchdog can be used only with an {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source editor built from source}.
+	Note: Watchdog can be used only with an {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source editor built from source}.
 </info-box>
 
 Install the [`@ckeditor/ckeditor5-watchdog`](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog) package:
@@ -44,20 +44,20 @@ watchdog.create( document.querySelector( '#editor' ), {
 } );
 ```
 
-In other words, your goal is to create a watchdog instance and make the watchdog create an instance of the editor you want to use. Watchdog will then create a new editor and if it ever crashes restart it by creating a new editor.
+In other words, your goal is to create a watchdog instance and make the watchdog create an instance of the editor you want to use. The watchdog will then create a new editor and if it ever crashes, restart it by creating a new editor.
 
 <info-box>
 	A new editor instance is created every time the watchdog detects a crash. Thus, the editor instance should not be kept in your application's state. Use the {@link module:watchdog/watchdog~Watchdog#editor `Watchdog#editor`} property instead.
 
-	It also means that any code that should be executed for any new editor instance should be either loaded as an editor plugin or executed in the callbacks defined by {@link module:watchdog/watchdog~Watchdog#setCreator `Watchdog#setCreator()`} and {@link module:watchdog/watchdog~Watchdog#setDestructor `Watchdog#setDestructor()`}. Read more about controlling editor creation/destruction in the next section.
+	It also means that any code that should be executed for any new editor instance should be either loaded as an editor plugin or executed in the callbacks defined by {@link module:watchdog/watchdog~Watchdog#setCreator `Watchdog#setCreator()`} and {@link module:watchdog/watchdog~Watchdog#setDestructor `Watchdog#setDestructor()`}. Read more about controlling the editor creation and destruction in the next section.
 </info-box>
 
-### Controlling editor creation/destruction
+### Controlling editor creation and destruction
 
 For more control over the creation and destruction of editor instances, you can use the {@link module:watchdog/watchdog~Watchdog#setCreator `Watchdog#setCreator()`} and {@link module:watchdog/watchdog~Watchdog#setDestructor `Watchdog#setDestructor()`} methods:
 
 ```js
-// Instantiate the watchdog manually (don't use the for() helper).
+// Instantiate the watchdog manually (do not use the for() helper).
 const watchdog = new Watchdog();
 
 watchdog.setCreator( ( elementOrData, editorConfig ) => {
@@ -136,8 +136,10 @@ const watchdog = new Watchdog( {
 
 ## Limitations
 
-The CKEditor 5 watchdog listens to uncaught errors which can be associated with the editor instance created by that watchdog. Currently, these errors are {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} so ones explicitly thrown by the editor (by its internal checks). This means that not every runtime error which crashed the editor can be caught which, in turn, means that not every crash can be detected.
+The CKEditor 5 watchdog listens to uncaught errors which can be associated with the editor instance created by that watchdog. Currently, these errors are {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} so those explicitly thrown by the editor (by its internal checks). This means that not every runtime error that crashed the editor can be caught which, in turn, means that not every crash can be detected.
 
 However, with time, the most "dangerous" places in the API will be covered with checks and `try-catch` blocks (allowing detecting unknown errors).
 
-<info-box>The watchdog does not handle errors thrown during editor initialization (by `Editor.create()`) and editor destruction (`Editor#destroy()`). Errors thrown at these stages mean that there is a serious problem in the code integrating the editor with your application and such problem cannot be easily fixed by restarting the editor.</info-box>
+<info-box>
+	The watchdog does not handle errors thrown during the editor initialization (by `Editor.create()`) and editor destruction (`Editor#destroy()`). Errors thrown at these stages mean that there is a serious problem in the code integrating the editor with your application and such problem cannot be easily fixed by restarting the editor.
+</info-box>

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ckeditor/ckeditor5-watchdog",
   "version": "10.0.1",
-  "description": "A watchdog feature for CKEditor 5 editors. It keeps a CKEditor 5 editor instance running",
+  "description": "A watchdog feature for CKEditor 5 editors. It keeps a CKEditor 5 editor instance running.",
   "keywords": [
     "ckeditor",
     "ckeditor5",

src/watchdog.js

@@ -18,7 +18,7 @@ import areConnectedThroughProperties from '@ckeditor/ckeditor5-utils/src/areconn
 /**
  * A watchdog for CKEditor 5 editors.
  *
- * See the {@glink features/watchdog Watchdog} feature guide to learn the rationale behind it and
+ * See the {@glink features/watchdog Watchdog feature guide} to learn the rationale behind it and
  * how to use it.
  */
 export default class Watchdog {
@@ -176,7 +176,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Sets the function that is responsible for editor creation.
+	 * Sets the function that is responsible for the editor creation.
 	 * It expects a function that should return a promise.
 	 *
 	 *		watchdog.setCreator( ( element, config ) => ClassicEditor.create( element, config ) );
@@ -188,7 +188,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Sets the function that is responsible for editor destruction.
+	 * Sets the function that is responsible for the editor destruction.
 	 * It expects a function that should return a promise or `undefined`.
 	 *
 	 *		watchdog.setDestructor( editor => editor.destroy() );
@@ -201,7 +201,7 @@ export default class Watchdog {
 
 	/**
 	 * Creates a watched editor instance using the creator passed to the {@link #setCreator `setCreator()`} method or
-	 * {@link module:watchdog/watchdog~Watchdog.for `Watchdog.for()`} helper.
+	 * the {@link module:watchdog/watchdog~Watchdog.for `Watchdog.for()`} helper.
 	 *
 	 * @param {HTMLElement|String|Object.<String|String>} elementOrData
 	 * @param {module:core/editor/editorconfig~EditorConfig} [config]
@@ -239,8 +239,8 @@ export default class Watchdog {
 
 		this._elementOrData = elementOrData;
 
-		// Clone config 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.
+		// 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 = cloneDeepWith( config, value => {
 			// Leave DOM references.
 			return isElement( value ) ? value : undefined;
@@ -298,7 +298,7 @@ export default class Watchdog {
 
 	/**
 	 * Saves the editor data, so it can be restored after the crash even if the data cannot be fetched at
-	 * the moment of a crash.
+	 * the moment of the crash.
 	 *
 	 * @private
 	 */
@@ -457,7 +457,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * A shorthand method for creating an instance of the watchdog. For the full usage see the
+	 * A shorthand method for creating an instance of the watchdog. For the full usage, see the
 	 * {@link ~Watchdog `Watchdog` class description}.
 	 *
 	 * Usage:
@@ -499,7 +499,8 @@ mix( Watchdog, ObservableMixin );
  *
  * @typedef {Object} WatchdogConfig
  *
- * @property {Number} [crashNumberLimit=3] A threshold specifying the number of editor errors (defaults to `3`).
+ * @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