Explorar o código

Improved docs.

Maciej Bukowski %!s(int64=6) %!d(string=hai) anos
pai
achega
2a6fb85818

+ 25 - 2
packages/ckeditor5-watchdog/docs/features/watchdog.md

@@ -47,7 +47,7 @@ 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.
 
 <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.
+	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.
 </info-box>
@@ -85,7 +85,7 @@ watchdog.create( elementOrData, editorConfig );
 
 Other useful {@link module:watchdog/watchdog~Watchdog methods, properties and events}:
 
- ```js
+```js
 watchdog.on( 'error', () => { console.log( 'Editor crashed.' ) } );
 watchdog.on( 'restart', () => { console.log( 'Editor was restarted.' ) } );
 
@@ -95,9 +95,32 @@ watchdog.destroy();
 // The current editor instance.
 watchdog.editor;
 
+// The current state of the editor.
+// The editor might be in one of the following states:
+// * `initializing`
+// * `ready`
+// * `crashed`
+// * `crashedPermanently`
+// This property is observable.
+watchdog.state;
+
+// Listen to state changes.
+watchdog.on( 'change:state' ( evt, name, currentState, prevState ) => {
+	console.log( `Editor changed from ${ currentState } to ${ prevState }` );
+} );
+
+// An array of editor crashes info.
 watchdog.crashes.forEach( crashInfo => console.log( crashInfo ) );
 ```
 
+### Configuration
+
+Both, the {@link module:watchdog/watchdog~Watchdog#constructor `Watchdog#constructor`} and the {@link module:watchdog/watchdog~Watchdog.for `Watchdog.for`} methods accept a {{@link module:watchdog/watchdog~WatchdogConfig configuration object} with the following optional properties:
+
+* `crashNumberLimit` - A threshold specifying the number of editor errors (defaults to `3`). 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.
+* `minimumNonErrorTimePeriod` - 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.
+* `waitingTime` - A minimum number of milliseconds between saving editor data internally, (defaults to 5000).
+
 ## 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.

+ 6 - 6
packages/ckeditor5-watchdog/src/watchdog.js

@@ -435,10 +435,10 @@ mix( Watchdog, ObservableMixin );
  * @typedef {Object} WatchdogConfig
  *
  * @property {Number} [crashNumberLimit=3] A threshold specifying the number of editor errors (defaults to `3`).
- * After this limit is reached and the `minimumNonErrorTimePeriod` is also reached the editor is not restarted
- * by the watchdog and the watchdog fires the {@link #crash `crash` event}. This prevents an infinite restart loop.
- * @property {Number} [minimumNonErrorTimePeriod=5000] An average amount of milliseconds between last editor errors.
- * When the period of time between errors is lower than that and the `crashNumberLimit` is also reached the editor is not
- * restarted by the watchdog and the watchdog fires the {@link #crash `crash` event}. This prevents an infinite restart loop.
- * @property {Number} [waitingTime=5000] A minimum amount of milliseconds between saving editor data internally.
+ * 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} [waitingTime=5000] A minimum number of milliseconds between saving editor data internally, (defaults to 5000).
  */