浏览代码

Docs and API docs improvements.

Maciej Bukowski 5 年之前
父节点
当前提交
e17d085567

+ 57 - 1
packages/ckeditor5-watchdog/docs/features/watchdog.md

@@ -213,7 +213,63 @@ watchdog.remove( [ 'editor1' ] );
 	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
+### Context watchdog API
+
+The ContextWatchdog feature provides the following API:
+
+```js
+// A simple initialization way with default Context creation and destruction functions:
+const watchdog = ContextWatchdog.for( Context, contextConfig, watchdogConfig )
+
+// An advanced initialization where custom creation and destruction functions can be passed:
+const watchdog = new ContextWatchdog( contextConfig, watchdogConfig )
+
+watchdog.setCreator( async config => {
+	const context = await Context.create( config ) );
+
+	// Do something when the context is initialized.
+
+	return context;
+} );
+
+watchdog.setDestructor( async context => {
+	// Do something before destroy.
+
+	await context.destroy();
+} );
+
+watchdog.create();
+
+// Adding, removing and getting item instances:
+watchdog.add( {
+	editor1: {
+		type: 'editor',
+		sourceElementOrData: editorSourceElementOrEditorData
+		config: editorConfig,
+		creator: createEditor,
+		destructor: destroyEditor,
+	},
+	// Possibly more items.
+} );
+
+watchdog.remove( [ 'editor1' ] );
+
+watchdog.add( itemConfig );
+
+// Given item instance.
+const editor1 = watchdog.get( 'editor1' );
+
+// Given item state.
+const editor1State = watchdog.getState( 'editor1' );
+
+// Context state.
+const contextState = watchdog.state;
+
+// Events
+watchdog.on( 'error', () => {} );
+
+watchdog.on( 'restart', () => {} );
+```
 
 ## Limitations
 

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

@@ -22,7 +22,8 @@ import getSubNodes from './utils/getsubnodes';
  */
 export default class ContextWatchdog extends Watchdog {
 	/**
-	 * The constructor should not be called directly. Use the {@link module:watchdog/contextwatchdog~ContextWatchdog.for} method instead.
+	 * The ContextWatchdog constructor. See {@glink features/watchdog Watchdog feature guide} to learn how to use it,
+	 * as using the constructor directly requires further steps to initialize the `ContextWatchdog`.
 	 *
 	 * @param {Object} [contextConfig] {@link module:core/context~Context} configuration.
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig] The watchdog configuration.
@@ -333,6 +334,8 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
+	 * Returns watchdog for the given item name.
+	 *
 	 * @protected
 	 * @param {String} itemName
 	 * @returns {module:watchdog/watchdog~Watchdog} Watchdog

+ 5 - 2
packages/ckeditor5-watchdog/src/watchdog.js

@@ -120,11 +120,11 @@ export default class Watchdog {
 		 */
 
 		/**
-		 * The handled instances.
+		 * The handled instance.
 		 *
 		 * @abstract
 		 * @protected
-		 * @member {Object} #_instance
+		 * @member {Object|undefined} #_instance
 		 */
 
 		/**
@@ -165,6 +165,9 @@ export default class Watchdog {
 		this._destructor = destructor;
 	}
 
+	/**
+	 * Destroys the watchdog and release the resources.
+	 */
 	destroy() {
 		this._stopErrorHandling();
 		this.stopListening();