瀏覽代碼

Improved API docs.

Maciej Bukowski 5 年之前
父節點
當前提交
c5169127e7
共有 1 個文件被更改,包括 51 次插入11 次删除
  1. 51 11
      packages/ckeditor5-watchdog/src/contextwatchdog.js

+ 51 - 11
packages/ckeditor5-watchdog/src/contextwatchdog.js

@@ -16,10 +16,13 @@ import getSubNodes from './utils/getsubnodes';
 
 /**
  * The Context Watchdog class.
+ *
+ * See the {@glink features/watchdog Watchdog feature guide} to learn the rationale behind it and
+ * how to use it.
  */
 export default class ContextWatchdog extends Watchdog {
 	/**
-	 * @param {Object} [contextConfig] Context configuration.
+	 * @param {Object} [contextConfig] {@link module:core/context~Context} configuration.
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig] The watchdog plugin configuration.
 	 */
 	constructor( contextConfig = {}, watchdogConfig = {} ) {
@@ -32,24 +35,33 @@ export default class ContextWatchdog extends Watchdog {
 		this._watchdogs = new Map();
 
 		/**
+		 * The current context instance.
+		 *
 		 * @private
 		 * @type {module:core/context~Context|null}
 		 */
 		this._context = null;
 
 		/**
+		 * Context props (nodes/references) that are gathered during the initial context creation
+		 * and are used to distinguish error origin.
+		 *
 		 * @private
 		 * @type {Set.<*>}
 		 */
 		this._contextProps = new Set();
 
 		/**
+		 * An action queue, which is used to handle async functions queuing.
+		 *
 		 * @private
 		 * @type {ActionQueue}
 		 */
 		this._actionQueue = new ActionQueue();
 
 		/**
+		 * Config for the {@link module:core/context~Context}.
+		 *
 		 * @private
 		 * @type {Object}
 		 */
@@ -62,6 +74,7 @@ export default class ContextWatchdog extends Watchdog {
 		 * @member {Object|undefined} #_config
 		 */
 
+		// Default destructor.
 		this._destructor = context => context.destroy();
 
 		this._actionQueue.onEmpty( () => {
@@ -82,19 +95,24 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Returns the watchdog for the added item by its name.
+	 * Returns the watchdog for the added item by its name. Depending on the item type
+	 * the instance can be retrieved from the watchdog.
 	 *
-	 * @param {String} name The watchdog name (the key under which the watchdog config was passed to the add() method).
+	 * 	const editorWatchdog = contextWatchdog.getWatchdog( 'editor1' );
+	 * 	const editor1 = editorWatchdog.editor;
+	 *
+	 * @param {String} name The item name (the key under which the item config was passed to the add() method).
 	 */
 	getWatchdog( name ) {
 		return this._watchdogs.get( name );
 	}
 
 	/**
-	 * Adds items to the watchdog. Internally watchdogs will be created for all of these items and they will be available
-	 *
+	 * Adds items to the watchdog. Internally watchdogs will be created for these items and they will be available later using
+	 * the {@link #getWatchdog} method.
 	 *
-	 * @param {Array.<Object.<string,module:watchdog/contextwatchdog~WatchdogItemConfiguration>>} itemConfigurations
+	 * @param {Array.<Object.<String,module:watchdog/contextwatchdog~WatchdogItemConfiguration>>} itemConfigurations
+	 * @returns {Promise}
 	 */
 	async add( itemConfigurations ) {
 		await this._actionQueue.enqueue( async () => {
@@ -135,9 +153,11 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * TODO
+	 * Removes item by its name from the created items. It destroys the internal watchdog for this item and remove
+	 * the item from the item list.
 	 *
 	 * @param {Array.<String>} itemNames
+	 * @returns {Promise}
 	 */
 	async remove( itemNames ) {
 		await this._actionQueue.enqueue( async () => {
@@ -157,6 +177,8 @@ export default class ContextWatchdog extends Watchdog {
 
 	/**
 	 * Waits for all previous actions.
+	 *
+	 * @returns {Promise}
 	 */
 	async waitForReady() {
 		await this._actionQueue.enqueue( () => { } );
@@ -164,6 +186,8 @@ export default class ContextWatchdog extends Watchdog {
 
 	/**
 	 * Creates the Context watchdog.
+	 *
+	 * @returns {Promise}
 	 */
 	async create() {
 		await this._actionQueue.enqueue( async () => {
@@ -174,6 +198,8 @@ export default class ContextWatchdog extends Watchdog {
 	/**
 	 * Destroys the `ContextWatchdog` and all added items. This method can't be undone.
 	 * Once the `ContextWatchdog` is destroyed new items can not be added.
+	 *
+	 * @returns {Promise}
 	 */
 	async destroy() {
 		await this._actionQueue.enqueue( async () => {
@@ -206,6 +232,8 @@ export default class ContextWatchdog extends Watchdog {
 
 	/**
 	 * @protected
+	 * @param {Boolean} isInternal If the action is internal and should be invoked immediately.
+	 * @returns {Promise}
 	 */
 	async _create( isInternal = false ) {
 		await this._actionQueue.enqueue( async () => {
@@ -227,7 +255,8 @@ export default class ContextWatchdog extends Watchdog {
 	/**
 	 * Destroys the Context and all added items.
 	 *
-	 * @param {Boolean} isInternal
+	 * @param {Boolean} isInternal If the action is internal and should be invoked immediately.
+	 * @returns {Promise}
 	 */
 	async _destroy( isInternal = false ) {
 		await this._actionQueue.enqueue( async () => {
@@ -252,6 +281,7 @@ export default class ContextWatchdog extends Watchdog {
 	 * Checks whether the error comes from the Context and not from Editor or ContextItem instances.
 	 *
 	 * @param {Error} error
+	 * @returns {Boolean}
 	 */
 	_isErrorComingFromThisInstance( error ) {
 		for ( const watchdog of this._watchdogs.values() ) {
@@ -266,10 +296,10 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 *
 	 * @param {module:core/context~Context} Context
 	 * @param {Object} [contextConfig]
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig]
+	 * @returns {module:watchdog/contextwatchdog~ContextWatchdog}
 	 */
 	static for( Context, contextConfig, watchdogConfig ) {
 		const watchdog = new this( contextConfig, watchdogConfig );
@@ -282,6 +312,11 @@ export default class ContextWatchdog extends Watchdog {
 	}
 }
 
+/**
+ * An action queue is used to queue async functions.
+ *
+ * @private
+ */
 class ActionQueue {
 	constructor() {
 		/**
@@ -300,6 +335,11 @@ class ActionQueue {
 		this._onEmptyCallbacks = [];
 	}
 
+	/**
+	 * A method used to register callbacks that will be run when the queue becomes empty.
+	 *
+	 * @param {Function} onEmptyCallback A callback that will be run whenever the queue becomes empty.
+	 */
 	onEmpty( onEmptyCallback ) {
 		this._onEmptyCallbacks.push( onEmptyCallback );
 	}
@@ -308,8 +348,8 @@ class ActionQueue {
 	 * It adds asynchronous actions (functions) to the queue and runs them one by one.
 	 * If the `isInternal` option is passed then it runs the provided function immediately.
 	 *
-	 * @param {Function} action
-	 * @param {Boolean} isInternal
+	 * @param {Function} action A function that should be enqueued.
+	 * @param {Boolean} isInternal If the action is internal and should be invoked immediately.
 	 */
 	async enqueue( action, isInternal = false ) {
 		// Run all internal callbacks immediately.