ソースを参照

Docs: More API docs and guide docs.

Maciej Bukowski 6 年 前
コミット
e250d9dd31

+ 23 - 6
packages/ckeditor5-watchdog/docs/features/watchdog.md

@@ -14,8 +14,8 @@ The {@link module:watchdog/watchdog~Watchdog} utility allows you to do exactly t
 It should be noticed that the most "dangerous" places in the API - like `editor.model.change()`, `editor.editing.view.change()`, emitters - are covered with checks and `try-catch` blocks that allow detecting unknown errors and restart editor when they occur.
 It should be noticed that the most "dangerous" places in the API - like `editor.model.change()`, `editor.editing.view.change()`, emitters - are covered with checks and `try-catch` blocks that allow detecting unknown errors and restart editor when they occur.
 
 
 Currently there are two available watchdogs, which can be used depending on your needs:
 Currently there are two available watchdogs, which can be used depending on your needs:
-* [Editor Watchdog](#editor-watchdog)
-* [Context Watchdog](#context-watchdog)
+* [editor watchdog](#editor-watchdog) - it fills the most basic scenario when only one editor is created
+* [context watchdog](#context-watchdog) - it
 
 
 ## Usage
 ## Usage
 
 
@@ -93,7 +93,7 @@ watchdog.create( elementOrData, editorConfig );
 	The default (not overridden) editor destructor is the `editor => editor.destroy()` function.
 	The default (not overridden) editor destructor is the `editor => editor.destroy()` function.
 </info-box>
 </info-box>
 
 
-#### API
+#### Editor watchdog API
 
 
 Other useful {@link module:watchdog/editorwatchdog~EditorWatchdog methods, properties and events}:
 Other useful {@link module:watchdog/editorwatchdog~EditorWatchdog methods, properties and events}:
 
 
@@ -170,10 +170,14 @@ import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
 import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
 import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
 import Context from '@ckeditor/ckeditor5-core/src/context';
 import Context from '@ckeditor/ckeditor5-core/src/context';
 
 
-// Create a watchdog for the context
-const watchdog = ContextWatchdog.for( Context );
+// Create a watchdog for the context and pass the context configuration:
+const watchdog = ContextWatchdog.for( Context, {
+	plugins: [],
 
 
-// Add editor instances.
+	// Rest of the configuration.
+} );
+
+// Add editor instances:
 watchdog.add( {
 watchdog.add( {
 	editor1: {
 	editor1: {
 		type: 'editor',
 		type: 'editor',
@@ -196,6 +200,19 @@ watchdog.add( {
 } );
 } );
 ```
 ```
 
 
+The Watchdog will keep the context and editor (and other types of items in the future) instances running
+that are added via the {@link module:watchdog/contextwatchdog~ContextWatchdog#add `ContextWatchdog#add` method}. This method can be called multiple times during the `ContextWatchdog` lifetime.
+
+To destroy one of the editor instances use the {@link module:watchdog/contextwatchdog~ContextWatchdog#remove `ContextWatchdog#remove` method}. This method can be called multiple times during the `ContextWatchdog` lifetime as well.
+
+```js
+watchdog.remove( [ 'editor1' ] );
+```
+
+<info-box>
+	Note that the above examples does not use promises returning by the context watchdog methods while these methods are asynchronous. You should not depend on these promises because they are resolved only once while your component might be restarted multiple times internally causing watchdog to unmount the editor and to mount again. Read further below for more information about events and watchdog states.
+</info-box>
+
 TODO
 TODO
 
 
 ## Limitations
 ## Limitations

+ 25 - 1
packages/ckeditor5-watchdog/src/contextwatchdog.js

@@ -22,6 +22,8 @@ import getSubNodes from './utils/getsubnodes';
  */
  */
 export default class ContextWatchdog extends Watchdog {
 export default class ContextWatchdog extends Watchdog {
 	/**
 	/**
+	 * The constructor should not be called directly. Use the {@link module:watchdog/contextwatchdog~ContextWatchdog.for} method instead.
+	 *
 	 * @param {Object} [contextConfig] {@link module:core/context~Context} configuration.
 	 * @param {Object} [contextConfig] {@link module:core/context~Context} configuration.
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig] The watchdog plugin configuration.
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig] The watchdog plugin configuration.
 	 */
 	 */
@@ -111,6 +113,18 @@ export default class ContextWatchdog extends Watchdog {
 	 * Adds items to the watchdog. Internally watchdogs will be created for these items and they will be available later using
 	 * Adds items to the watchdog. Internally watchdogs will be created for these items and they will be available later using
 	 * the {@link #getWatchdog} method.
 	 * the {@link #getWatchdog} method.
 	 *
 	 *
+	 * 	watchdog.add( {
+	 *		editor1: {
+	 *			type: 'editor',
+	 *			sourceElementOrData: document.querySelector( '#editor' ),
+	 *			config: {
+	 *				plugins: [ Essentials, Paragraph, Bold, Italic ],
+	 *				toolbar: [ 'bold', 'italic', 'alignment' ]
+	 *			},
+	 *			creator: ( element, config ) => ClassicEditor.create( element, config )
+	 *		}
+	 * 	}
+	 *
 	 * // @param {Array.<Object.<String,module:watchdog/contextwatchdog~WatchdogItemConfiguration>>} itemConfigurations
 	 * // @param {Array.<Object.<String,module:watchdog/contextwatchdog~WatchdogItemConfiguration>>} itemConfigurations
 	 * @param {Array.<Object>} itemConfigurations
 	 * @param {Array.<Object>} itemConfigurations
 	 * @returns {Promise}
 	 * @returns {Promise}
@@ -300,6 +314,14 @@ export default class ContextWatchdog extends Watchdog {
 	}
 	}
 
 
 	/**
 	/**
+	 * Creates context watchdog for the given Context constructor, context configuration and watchdog configuration.
+	 *
+	 * 	const contextWatchdog = ContextWatchdog.for( Context, {
+	 * 		plugins: []
+	 * 	} );
+	 *
+	 * 	contextWatchdog.add( watchdogItem );
+	 *
 	 * @param {module:core/context~Context} Context
 	 * @param {module:core/context~Context} Context
 	 * @param {Object} [contextConfig]
 	 * @param {Object} [contextConfig]
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig]
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig]
@@ -413,7 +435,7 @@ class ActionQueue {
 }
 }
 
 
 /**
 /**
- * The WatchdogItemConfiguration interface
+ * The WatchdogItemConfiguration interface.
  *
  *
  * @typedef {module:watchdog/contextwatchdog~EditorWatchdogConfiguration} module:watchdog/contextwatchdog~WatchdogItemConfiguration
  * @typedef {module:watchdog/contextwatchdog~EditorWatchdogConfiguration} module:watchdog/contextwatchdog~WatchdogItemConfiguration
  */
  */
@@ -423,6 +445,8 @@ class ActionQueue {
  *
  *
  * @typedef {Object} module:watchdog/contextwatchdog~EditorWatchdogConfiguration
  * @typedef {Object} module:watchdog/contextwatchdog~EditorWatchdogConfiguration
  *
  *
+ * @property {'editor'} type A type of the item to create. In this case it should be set to the `editor`.
+ *
  * @property {Function} creator A function that needs to be called to initialize the editor.
  * @property {Function} creator A function that needs to be called to initialize the editor.
  *
  *
  * @property {Function} [destructor] A function that is responsible for destructing the editor.
  * @property {Function} [destructor] A function that is responsible for destructing the editor.