浏览代码

Reformatted API docs.

Piotrek Koszuliński 9 年之前
父节点
当前提交
48f5bf275b

+ 14 - 10
packages/ckeditor5-undo/src/basecommand.js

@@ -3,14 +3,18 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module undo/basecommand
+ */
+
 import Command from '../core/command/command.js';
 import transform from '../engine/model/delta/transform.js';
 
 /**
- * Base class for undo feature commands: {@link undo.UndoCommand} and {@link undo.RedoCommand}.
+ * Base class for undo feature commands: {@link module:undo/undocommand~UndoCommand} and {@link module:undo/redocommand~RedoCommand}.
  *
  * @protected
- * @memberOf undo
+ * @extends module:core/command/command~Command
  */
 export default class BaseCommand extends Command {
 	constructor( editor ) {
@@ -19,11 +23,11 @@ export default class BaseCommand extends Command {
 		/**
 		 * Stack of items stored by the command. These are pairs of:
 		 *
-		 * * {@link engine.model.Batch batch} saved by the command,
-		 * * {@link engine.model.Selection selection} state at the moment of saving the batch.
+		 * * {@link module:engine/model/batch~Batch batch} saved by the command,
+		 * * {@link module:engine/model/selection~Selection selection} state at the moment of saving the batch.
 		 *
 		 * @protected
-		 * @member {Array} undo.BaseCommand#_stack
+		 * @member {Array} #_stack
 		 */
 		this._stack = [];
 
@@ -31,7 +35,7 @@ export default class BaseCommand extends Command {
 		 * Stores all batches that were created by this command.
 		 *
 		 * @protected
-		 * @member {WeakSet.<engine.model.Batch>} undo.BaseCommand#_createdBatches
+		 * @member {WeakSet.<module:engine/model/batch~Batch>} #_createdBatches
 		 */
 		this._createdBatches = new WeakSet();
 
@@ -40,10 +44,10 @@ export default class BaseCommand extends Command {
 	}
 
 	/**
-	 * Stores a batch in the command, together with the selection state of the {@link engine.model.Document document}
+	 * Stores a batch in the command, together with the selection state of the {@link module:engine/model/document~Document document}
 	 * created by the editor which this command is registered to.
 	 *
-	 * @param {engine.model.Batch} batch The batch to add.
+	 * @param {module:engine/model/batch~Batch} batch The batch to add.
 	 */
 	addBatch( batch ) {
 		const selection = {
@@ -71,10 +75,10 @@ export default class BaseCommand extends Command {
 	}
 
 	/**
-	 * Restores the {@link engine.model.Document#selection document selection} state after a batch was undone.
+	 * Restores the {@link module:engine/model/document~Document#selection document selection} state after a batch was undone.
 	 *
 	 * @protected
-	 * @param {Array.<engine.model.Range>} ranges Ranges to be restored.
+	 * @param {Array.<module:engine/model/range~Range>} ranges Ranges to be restored.
 	 * @param {Boolean} isBackward A flag describing whether the restored range was selected forward or backward.
 	 */
 	_restoreSelection( ranges, isBackward, deltas ) {

+ 17 - 12
packages/ckeditor5-undo/src/redocommand.js

@@ -3,25 +3,30 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module undo/redocommand
+ */
+
 import BaseCommand from './basecommand.js';
 import { transformDelta as transformDelta } from './basecommand.js';
 
 /**
- * The redo command stores {@link engine.model.Batch batches} that were used to undo a batch by {@link undo.UndoCommand UndoCommand}.
- * It is able to redo a previously undone batch by reversing the undoing batches created by `UndoCommand`. The reversed batch is
- * also transformed by batches from {@link engine.model.Document#history history} that happened after it and are not other redo batches.
+ * The redo command stores {@link module:engine/model/batch~Batch batches} that were used to undo a batch by
+ * {@link module:undo/undocommand~UndoCommand}. It is able to redo a previously undone batch by reversing the undoing
+ * batches created by `UndoCommand`. The reversed batch is also transformed by batches from
+ * {@link module:engine/model/document~Document#history history} that happened after it and are not other redo batches.
  *
- * The redo command also takes care of restoring the {@link engine.model.Document#selection document selection} to the state before
- * an undone batch was applied.
+ * The redo command also takes care of restoring the {@link module:engine/model/document~Document#selection document selection}
+ * to the state before an undone batch was applied.
  *
- * @memberOf undo
- * @extends undo.BaseCommand
+ * @extends module:undo/basecommand~BaseCommand
  */
 export default class RedoCommand extends BaseCommand {
 	/**
-	 * Executes the command. This method reverts the last {@link engine.model.Batch batch} added to the command's stack, applies
-	 * the reverted and transformed version on the {@link engine.model.Document document} and removes the batch from the stack.
-	 * Then, it restores the {@link engine.model.Document#selection document selection}.
+	 * Executes the command. This method reverts the last {@link module:engine/model/batch~Batch batch} added to
+	 * the command's stack, applies the reverted and transformed version on the
+	 * {@link module:engine/model/document~Document document} and removes the batch from the stack.
+	 * Then, it restores the {@link module:engine/model/document~Document#selection document selection}.
 	 *
 	 * @protected
 	 */
@@ -51,10 +56,10 @@ export default class RedoCommand extends BaseCommand {
 
 	/**
 	 * Redoes a batch by reversing the batch that has undone it, transforming that batch and applying it. This is
-	 * a helper method for {@link undo.RedoCommand#_doExecute}.
+	 * a helper method for {@link #_doExecute}.
 	 *
 	 * @private
-	 * @param {engine.model.Batch} storedBatch The batch whose deltas will be reversed, transformed and applied.
+	 * @param {module:engine/model/batch~Batch} storedBatch The batch whose deltas will be reversed, transformed and applied.
 	 */
 	_redo( storedBatch ) {
 		const document = this.editor.document;

+ 17 - 12
packages/ckeditor5-undo/src/undo.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module undo/undo
+ */
+
 import Plugin from '../core/plugin.js';
 import UndoEngine from './undoengine.js';
 import ButtonView from '../ui/button/buttonview.js';
@@ -10,12 +14,14 @@ import ButtonView from '../ui/button/buttonview.js';
 /**
  * The undo feature. It introduces the Undo and Redo buttons to the editor.
  *
- * Below is the explanation of the undo mechanism working together with {@link engine.model.History History}:
+ * Below is the explanation of the undo mechanism working together with {@link module:engine/model/history~History History}:
  *
- * Whenever a {@link engine.model.Delta delta} is applied to the {@link engine.model.Document document}, it is saved to
- * `History` as is. The {@link engine.model.Batch batch} that owns that delta is also saved, in {@link undo.UndoCommand},
- * together with the selection that was present in the document before the delta was applied. A batch is saved instead of the delta
- * because changes are undone batch-by-batch, not delta-by-delta and a batch is seen as one undo step.
+ * Whenever a {@link module:engine/model/delta/delta~Delta delta} is applied to the
+ * {@link module:engine/model/document~Document document}, it is saved to `History` as is.
+ * The {@link module:engine/model/batch~Batch batch} that owns that delta is also saved, in
+ * {@link module:undo/undocommand~UndoCommand}, together with the selection that was present in the document before the
+ * delta was applied. A batch is saved instead of the delta because changes are undone batch-by-batch, not delta-by-delta
+ * and a batch is seen as one undo step.
  *
  * After some changes happen to the document, the `History` and `UndoCommand` stack can be represented as follows:
  *
@@ -36,9 +42,9 @@ import ButtonView from '../ui/button/buttonview.js';
  * so if a batch has delta `X`, `Y`, `Z`, reversed deltas `Zr`, `Yr` and `Xr` need to be applied. Otherwise reversed delta
  * `Xr` would operate on a wrong document state, because delta `X` does not know that deltas `Y` and `Z` happened.
  *
- * After deltas from an undone batch got {@link engine.model.Delta#getReversed reversed}, one needs to make sure if they are
- * ready to be applied. In the scenario above, delta `C3` is the last delta and `C3r` bases on up-to-date document state, so
- * it can be applied to the document.
+ * After deltas from an undone batch got {@link module:engine/model/delta/delta~Delta#getReversed reversed},
+ * one needs to make sure if they are ready to be applied. In the scenario above, delta `C3` is the last delta and `C3r`
+ * bases on up-to-date document state, so it can be applied to the document.
  *
  *		  History                           Undo stack
  *		===========             ==================================
@@ -58,7 +64,7 @@ import ButtonView from '../ui/button/buttonview.js';
  * operational transformation algorithms assume there is no connection between two transformed operations when resolving
  * conflicts, which is true for example for collaborative editing, but is not true for the undo algorithm.
  *
- * To prevent both problems, `History` introduces an API to {@link engine.model.History#removeDelta remove}
+ * To prevent both problems, `History` introduces an API to {@link module:engine/model/history~History#removeDelta remove}
  * deltas from history. It is used to remove undone and undoing deltas after they are applied. It feels right &mdash; since when a
  * delta is undone or reversed, it is "removed" and there should be no sign of it in the history (fig. 1).
  *
@@ -92,7 +98,7 @@ import ButtonView from '../ui/button/buttonview.js';
  * It is an obvious error &mdash; transforming by that delta would lead to incorrect results or "repeating" history would
  * produce a different document than the actual one.
  *
- * To prevent this situation, `B3` needs to also be {@link engine.model.History#updateDelta updated} in history.
+ * To prevent this situation, `B3` needs to also be {@link module:engine/model/history~History#updateDelta updated} in history.
  * It should be kept in a state that "does not remember" deltas that were removed from history. It is easily
  * achieved while transforming the reversed delta. For example, when `C2r` is transformed by `B3`, at the same time `B3` is
  * transformed by `C2r`. Transforming `B3` that remembers `C2` by a delta reversing `C2` effectively makes `B3` "forget" about `C2`.
@@ -116,8 +122,7 @@ import ButtonView from '../ui/button/buttonview.js';
  * The same algorithm applies: deltas from a batch (i.e. `A1`) are reversed and then transformed by deltas stored in history,
  * simultaneously updating them. Then deltas are applied to the document and removed from history (fig. 5).
  *
- * @memberOf undo
- * @extends core.Plugin
+ * @extends module:core/plugin~Plugin
  */
 export default class Undo extends Plugin {
 	/**

+ 25 - 16
packages/ckeditor5-undo/src/undocommand.js

@@ -3,29 +3,32 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module undo/undocommand
+ */
+
 import BaseCommand from './basecommand.js';
 import { transformDelta, transformRangesByDeltas } from './basecommand.js';
 
 /**
- * The undo command stores {@link engine.model.Batch batches} applied to the {@link engine.model.Document document}
- * ble to undo a batch by reversing it and transforming by other batches from {@link engine.model.Document#history history}
- * that happened after the reversed batch.
+ * The undo command stores {@link module:engine/model/batch~Batch batches} applied to the
+ * {@link module:engine/model/document~Document document} ble to undo a batch by reversing it and transforming by
+ * other batches from {@link module:engine/model/document~Document#history history} that happened after the reversed batch.
  *
- * The undo command also takes care of restoring the {@link engine.model.Document#selection document selection} to the state before
- * the undone batch was applied.
+ * The undo command also takes care of restoring the {@link module:engine/model/document~Document#selection document selection}
+ * to the state before the undone batch was applied.
  *
- * @memberOf undo
- * @extends undo.BaseCommand
+ * @extends module:undo/basecommand~BaseCommand
  */
 export default class UndoCommand extends BaseCommand {
 	/**
-	 * Executes the command. This method reverts a {@link engine.model.Batch batch} added to the command's stack, transforms
-	 * and applies the reverted version on the {@link engine.model.Document document} and removes the batch from the stack.
-	 * Then, it restores the {@link engine.model.Document#selection document selection}.
+	 * Executes the command. This method reverts a {@link module:engine/model/batch~Batch batch} added to the command's stack, transforms
+	 * and applies the reverted version on the {@link module:engine/model/document~Document document} and removes the batch from the stack.
+	 * Then, it restores the {@link module:engine/model/document~Document#selection document selection}.
 	 *
 	 * @protected
-	 * @fires undo.UndoCommand#event:revert
-	 * @param {engine.model.Batch} [batch] A batch that should be undone. If not set, the last added batch will be undone.
+	 * @fires revert
+	 * @param {module:engine/model/batch~Batch} [batch] A batch that should be undone. If not set, the last added batch will be undone.
 	 */
 	_doExecute( batch = null ) {
 		// If batch is not given, set `batchIndex` to the last index in command stack.
@@ -48,8 +51,8 @@ export default class UndoCommand extends BaseCommand {
 	}
 
 	/**
-	 * Returns an index in {@link undo.BaseCommand#_stack} pointing to the item that is storing a batch that has a given
-	 * {@link engine.model.Batch#baseVersion}.
+	 * Returns an index in {@link module:undo/basecommand~BaseCommand#_stack} pointing to the item that is storing a
+	 * batch that has a given {@link module:engine/model/batch~Batch#baseVersion}.
 	 *
 	 * @private
 	 * @param {Number} baseVersion The base version of the batch to find.
@@ -67,10 +70,10 @@ export default class UndoCommand extends BaseCommand {
 
 	/**
 	 * Undoes a batch by reversing a batch from history, transforming that reversed batch and applying it. This is
-	 * a helper method for {@link undo.UndoCommand#_doExecute}.
+	 * a helper method for {@link #_doExecute}.
 	 *
 	 * @private
-	 * @param {engine.model.Batch} batchToUndo A batch whose deltas will be reversed, transformed and applied.
+	 * @param {module:engine/model/batch~Batch} batchToUndo A batch whose deltas will be reversed, transformed and applied.
 	 */
 	_undo( batchToUndo ) {
 		const document = this.editor.document;
@@ -177,3 +180,9 @@ export default class UndoCommand extends BaseCommand {
 		return undoingBatch;
 	}
 }
+
+/**
+ * Fired when execution of the command reverts some batch.
+ *
+ * @event revert
+ */

+ 13 - 10
packages/ckeditor5-undo/src/undoengine.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module undo/undoengine
+ */
+
 import Plugin from '../core/plugin.js';
 import UndoCommand from './undocommand.js';
 import RedoCommand from './redocommand.js';
@@ -11,10 +15,9 @@ import RedoCommand from './redocommand.js';
  * The undo engine feature.
  *
  * Undo brings in possibility to undo and redo changes done in the model by deltas through
- * the {@link engine.model.Document#batch Batch API}.
+ * the {@link module:engine/model/document~Document#batch Batch API}.
  *
- * @memberOf undo
- * @extends core.Plugin
+ * @extends module:core/plugin~Plugin
  */
 export default class UndoEngine extends Plugin {
 	/**
@@ -24,26 +27,26 @@ export default class UndoEngine extends Plugin {
 		super( editor );
 
 		/**
-		 * The command that manages undo {@link engine.model.Batch batches} stack (history).
-		 * Created and registered during the {@link undo.UndoEngine#init feature initialization}.
+		 * The command that manages undo {@link module:engine/model/batch~Batch batches} stack (history).
+		 * Created and registered during the {@link #init feature initialization}.
 		 *
 		 * @private
-		 * @member {undo.UndoEngineCommand} undo.UndoEngine#_undoCommand
+		 * @member {undo.UndoEngineCommand} #_undoCommand
 		 */
 
 		/**
-		 * The command that manages redo {@link engine.model.Batch batches} stack (history).
-		 * Created and registered during the {@link undo.UndoEngine#init feature initialization}.
+		 * The command that manages redo {@link module:engine/model/batch~Batch batches} stack (history).
+		 * Created and registered during the {@link #init feature initialization}.
 		 *
 		 * @private
-		 * @member {undo.UndoEngineCommand} undo.UndoEngine#_redoCommand
+		 * @member {undo.UndoEngineCommand} #_redoCommand
 		 */
 
 		/**
 		 * Keeps track of which batches were registered in undo.
 		 *
 		 * @private
-		 * @member {WeakSet.<engine.model.Batch>} undo.UndoEngine#_batchRegistry
+		 * @member {WeakSet.<module:engine/model/batch~Batch>}
 		 */
 		this._batchRegistry = new WeakSet();
 	}