Browse Source

API docs corrections.

Piotrek Koszuliński 10 years ago
parent
commit
b43bfab395

+ 4 - 4
packages/ckeditor5-engine/src/document/delta/changedelta.js

@@ -16,7 +16,7 @@ CKEDITOR.define( [
 ], ( Delta, register, ChangeOperation, Position, Range, Attribute, Element ) => {
 ], ( Delta, register, ChangeOperation, Position, Range, Attribute, Element ) => {
 	/**
 	/**
 	 * To provide specific OT behavior and better collisions solving, change methods ({@link document.Transaction#setAttr}
 	 * To provide specific OT behavior and better collisions solving, change methods ({@link document.Transaction#setAttr}
-	 * and {@link document.Transaction#removeAttr}) use `ChangeDelta` class which inherit from `Delta` class and may
+	 * and {@link document.Transaction#removeAttr}) use `ChangeDelta` class which inherits from the `Delta` class and may
 	 * overwrite some methods.
 	 * overwrite some methods.
 	 *
 	 *
 	 * @class document.delta.ChangeDelta
 	 * @class document.delta.ChangeDelta
@@ -27,11 +27,11 @@ CKEDITOR.define( [
 	 * Sets the value of the attribute of the node or on the range.
 	 * Sets the value of the attribute of the node or on the range.
 	 *
 	 *
 	 * @chainable
 	 * @chainable
-	 * @memberOf document.Transaction
 	 * @method setAttr
 	 * @method setAttr
+	 * @memberOf document.Transaction
 	 * @param {String} key Attribute key.
 	 * @param {String} key Attribute key.
 	 * @param {Mixed} value Attribute new value.
 	 * @param {Mixed} value Attribute new value.
-	 * @param {document.Node|document.Range} range Node or range on which the attribute will be set.
+	 * @param {document.Node|document.Range} nodeOrRange Node or range on which the attribute will be set.
 	 */
 	 */
 	register( 'setAttr', change );
 	register( 'setAttr', change );
 
 
@@ -39,8 +39,8 @@ CKEDITOR.define( [
 	 * Removes an attribute from the range.
 	 * Removes an attribute from the range.
 	 *
 	 *
 	 * @chainable
 	 * @chainable
-	 * @memberOf document.Transaction
 	 * @method removeAttr
 	 * @method removeAttr
+	 * @memberOf document.Transaction
 	 * @param {String} key Attribute key.
 	 * @param {String} key Attribute key.
 	 * @param {document.Node|document.Range} nodeOrRange Node or range on which the attribute will be removed.
 	 * @param {document.Node|document.Range} nodeOrRange Node or range on which the attribute will be removed.
 	 */
 	 */

+ 2 - 2
packages/ckeditor5-engine/src/document/delta/delta.js

@@ -10,9 +10,9 @@ CKEDITOR.define( [], () => {
 	 * Base class for all deltas.
 	 * Base class for all deltas.
 	 *
 	 *
 	 * Delta is a single, from the user action point of view, change in the editable document, like insert, split or
 	 * Delta is a single, from the user action point of view, change in the editable document, like insert, split or
-	 * rename element. Delta is composed of operations, which are unit changes need to be done to execute user action.
+	 * rename element. Delta is composed of operations, which are unit changes needed to be done to execute user action.
 	 *
 	 *
-	 * Multiple deltas are grouped as a single {@link document.Transaction}.
+	 * Multiple deltas are grouped into a single {@link document.Transaction}.
 	 *
 	 *
 	 * @class document.delta.Delta
 	 * @class document.delta.Delta
 	 */
 	 */

+ 4 - 4
packages/ckeditor5-engine/src/document/delta/insertdelta.js

@@ -11,22 +11,22 @@ CKEDITOR.define( [
 	'document/operation/insertoperation'
 	'document/operation/insertoperation'
 ], ( Delta, register, InsertOperation ) => {
 ], ( Delta, register, InsertOperation ) => {
 	/**
 	/**
-	 * To provide specific OT behavior and better collisions solving, {@link document.Transaction#insert} method
-	 * use `InsertDelta` class which inherit from `Delta` class and may overwrite some methods.
+	 * To provide specific OT behavior and better collisions solving, the {@link document.Transaction#insert} method
+	 * uses the `InsertDelta` class which inherits from the `Delta` class and may overwrite some methods.
 	 *
 	 *
 	 * @class document.delta.InsertDelta
 	 * @class document.delta.InsertDelta
 	 */
 	 */
 	class InsertDelta extends Delta {}
 	class InsertDelta extends Delta {}
 
 
 	/**
 	/**
-	 * Insert node or nodes at the given position.
+	 * Inserts a node or nodes at the given position.
 	 *
 	 *
 	 * @chainable
 	 * @chainable
 	 * @memberOf document.Transaction
 	 * @memberOf document.Transaction
 	 * @method insert
 	 * @method insert
 	 * @param {document.Position} position Position of insertion.
 	 * @param {document.Position} position Position of insertion.
 	 * @param {document.Node|document.Text|document.NodeList|String|Iterable} nodes The list of nodes to be inserted.
 	 * @param {document.Node|document.Text|document.NodeList|String|Iterable} nodes The list of nodes to be inserted.
-	 * List of nodes can be any type accepted by the {@link document.NodeList} constructor.
+	 * List of nodes can be of any type accepted by the {@link document.NodeList} constructor.
 	 */
 	 */
 	register( 'insert', ( doc, transaction, position, nodes ) => {
 	register( 'insert', ( doc, transaction, position, nodes ) => {
 		const delta = new InsertDelta();
 		const delta = new InsertDelta();

+ 3 - 3
packages/ckeditor5-engine/src/document/delta/mergedelta.js

@@ -16,21 +16,21 @@ CKEDITOR.define( [
 ], ( Delta, register, Position, Element, RemoveOperation, MoveOperation, CKEditorError ) => {
 ], ( Delta, register, Position, Element, RemoveOperation, MoveOperation, CKEditorError ) => {
 	/**
 	/**
 	 * To provide specific OT behavior and better collisions solving, {@link document.Transaction#merge} method
 	 * To provide specific OT behavior and better collisions solving, {@link document.Transaction#merge} method
-	 * use `MergeDelta` class which inherit from `Delta` class and may overwrite some methods.
+	 * uses the `MergeDelta` class which inherits from the `Delta` class and may overwrite some methods.
 	 *
 	 *
 	 * @class document.delta.MergeDelta
 	 * @class document.delta.MergeDelta
 	 */
 	 */
 	class MergeDelta extends Delta {}
 	class MergeDelta extends Delta {}
 
 
 	/**
 	/**
-	 * Merge two siblings at the given position.
+	 * Merges two siblings at the given position.
 	 *
 	 *
 	 * Node before and after the position have to be an element. Otherwise `transaction-merge-no-element-before` or
 	 * Node before and after the position have to be an element. Otherwise `transaction-merge-no-element-before` or
 	 * `transaction-merge-no-element-after` error will be thrown.
 	 * `transaction-merge-no-element-after` error will be thrown.
 	 *
 	 *
 	 * @chainable
 	 * @chainable
-	 * @memberOf document.Transaction
 	 * @method merge
 	 * @method merge
+	 * @memberOf document.Transaction
 	 * @param {document.Position} position Position of merge.
 	 * @param {document.Position} position Position of merge.
 	 */
 	 */
 	register( 'merge', ( doc, transaction, position ) => {
 	register( 'merge', ( doc, transaction, position ) => {

+ 3 - 3
packages/ckeditor5-engine/src/document/delta/removedelta.js

@@ -12,18 +12,18 @@ CKEDITOR.define( [
 ], ( Delta, register, RemoveOperation ) => {
 ], ( Delta, register, RemoveOperation ) => {
 	/**
 	/**
 	 * To provide specific OT behavior and better collisions solving, {@link document.Transaction#remove} method
 	 * To provide specific OT behavior and better collisions solving, {@link document.Transaction#remove} method
-	 * use `RemoveDelta` class which inherit from `Delta` class and may overwrite some methods.
+	 * uses the `RemoveDelta` class which inherits from the `Delta` class and may overwrite some methods.
 	 *
 	 *
 	 * @class document.delta.RemoveDelta
 	 * @class document.delta.RemoveDelta
 	 */
 	 */
 	class RemoveDelta extends Delta {}
 	class RemoveDelta extends Delta {}
 
 
 	/**
 	/**
-	 * Remove nodes starting at the given position.
+	 * Removes nodes starting from the given position.
 	 *
 	 *
 	 * @chainable
 	 * @chainable
-	 * @memberOf document.Transaction
 	 * @method remove
 	 * @method remove
+	 * @memberOf document.Transaction
 	 * @param {document.Position} position Position before the first node to remove.
 	 * @param {document.Position} position Position before the first node to remove.
 	 * @param {Number} howMany How many nodes to remove.
 	 * @param {Number} howMany How many nodes to remove.
 	 */
 	 */

+ 12 - 10
packages/ckeditor5-engine/src/document/delta/splitdelta.js

@@ -15,22 +15,22 @@ CKEDITOR.define( [
 	'ckeditorerror'
 	'ckeditorerror'
 ], ( Delta, register, Position, Element, InsertOperation, MoveOperation, CKEditorError ) => {
 ], ( Delta, register, Position, Element, InsertOperation, MoveOperation, CKEditorError ) => {
 	/**
 	/**
-	 * To provide specific OT behavior and better collisions solving, {@link document.Transaction#split} method
-	 * use `SplitDelta` class which inherit from `Delta` class and may overwrite some methods.
+	 * To provide specific OT behavior and better collisions solving, the {@link document.Transaction#split} method
+	 * uses `SplitDelta` class which inherits from the `Delta` class and may overwrite some methods.
 	 *
 	 *
 	 * @class document.delta.SplitDelta
 	 * @class document.delta.SplitDelta
 	 */
 	 */
 	class SplitDelta extends Delta {}
 	class SplitDelta extends Delta {}
 
 
 	/**
 	/**
-	 * Split a node at the given position.
+	 * Splits a node at the given position.
 	 *
 	 *
-	 * This can not be a position inside a root element, method will throw `transaction-split-root` if you try to split
-	 * root element.
+	 * This cannot be a position inside the root element. The `transaction-split-root` error will be thrown if
+	 * you try to split the root element.
 	 *
 	 *
 	 * @chainable
 	 * @chainable
-	 * @memberOf document.Transaction
 	 * @method split
 	 * @method split
+	 * @memberOf document.Transaction
 	 * @param {document.Position} position Position of split.
 	 * @param {document.Position} position Position of split.
 	 */
 	 */
 	register( 'split', ( doc, transaction, position ) => {
 	register( 'split', ( doc, transaction, position ) => {
@@ -39,16 +39,16 @@ CKEDITOR.define( [
 
 
 		if ( !splitElement.parent ) {
 		if ( !splitElement.parent ) {
 			/**
 			/**
-			 * Root element can not be splitted.
+			 * Root element can not be split.
 			 *
 			 *
 			 * @error transaction-split-root
 			 * @error transaction-split-root
 			 */
 			 */
-			throw new CKEditorError( 'transaction-split-root: Root element can not be splitted.' );
+			throw new CKEditorError( 'transaction-split-root: Root element can not be split.' );
 		}
 		}
 
 
 		const copy = new Element( splitElement.name, splitElement.getAttrIterator() );
 		const copy = new Element( splitElement.name, splitElement.getAttrIterator() );
-
 		const insert = new InsertOperation( Position.createAfter( splitElement ), copy, doc.version );
 		const insert = new InsertOperation( Position.createAfter( splitElement ), copy, doc.version );
+
 		doc.applyOperation( insert );
 		doc.applyOperation( insert );
 		delta.addOperation( insert );
 		delta.addOperation( insert );
 
 
@@ -56,7 +56,9 @@ CKEDITOR.define( [
 			position,
 			position,
 			Position.createFromParentAndOffset( copy, 0 ),
 			Position.createFromParentAndOffset( copy, 0 ),
 			splitElement.getChildCount() - position.offset,
 			splitElement.getChildCount() - position.offset,
-			doc.version );
+			doc.version
+		);
+
 		doc.applyOperation( move );
 		doc.applyOperation( move );
 		delta.addOperation( move );
 		delta.addOperation( move );
 
 

+ 11 - 12
packages/ckeditor5-engine/src/document/delta/transaction-base.js

@@ -14,18 +14,18 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
 	 *
 	 *
 	 * For example to create two separate undo steps you can call:
 	 * For example to create two separate undo steps you can call:
 	 *
 	 *
-	 *	  doc.makeTransaction().insert( firstPosition, 'foo' );
-	 *	  doc.makeTransaction().insert( secondPosition, 'bar' );
+	 *		doc.makeTransaction().insert( firstPosition, 'foo' );
+	 *		doc.makeTransaction().insert( secondPosition, 'bar' );
 	 *
 	 *
 	 * To create a single undo step:
 	 * To create a single undo step:
 	 *
 	 *
-	 *	  const transaction = doc.makeTransaction()
-	 *	  transaction.insert( firstPosition, 'foo' );
-	 *	  transaction.insert( secontPosition, 'bar' );
+	 *		const transaction = doc.makeTransaction()
+	 *		transaction.insert( firstPosition, 'foo' );
+	 *		transaction.insert( secontPosition, 'bar' );
 	 *
 	 *
 	 * Note that all document modification methods (insert, remove, split, etc.) are chainable so you can shorten code to:
 	 * Note that all document modification methods (insert, remove, split, etc.) are chainable so you can shorten code to:
 	 *
 	 *
-	 *	  doc.makeTransaction().insert( firstPosition, 'foo' ).insert( secontPosition, 'bar' );
+	 *		doc.makeTransaction().insert( firstPosition, 'foo' ).insert( secontPosition, 'bar' );
 	 *
 	 *
 	 * @class document.Transaction
 	 * @class document.Transaction
 	 */
 	 */
@@ -60,7 +60,6 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
 		 * to add created deltas.
 		 * to add created deltas.
 		 *
 		 *
 		 * @param {document.delta.Delta} delta Delta to add.
 		 * @param {document.delta.Delta} delta Delta to add.
-		 *
 		 * @return {document.delta.Delta} Added delta.
 		 * @return {document.delta.Delta} Added delta.
 		 */
 		 */
 		addDelta( delta ) {
 		addDelta( delta ) {
@@ -79,16 +78,16 @@ CKEDITOR.define( [ 'ckeditorerror' ], ( CKEditorError ) => {
 
 
 		/**
 		/**
 		 * Static method to register transaction methods. To make code scalable transaction do not have modification
 		 * Static method to register transaction methods. To make code scalable transaction do not have modification
-		 * methods build in. They can be registered using this method.
+		 * methods built in. They can be registered using this method.
 		 *
 		 *
-		 * This method check if there is no naming collision and throw `transaction-register-taken` if the method name
+		 * This method checks if there is no naming collision and throw `transaction-register-taken` if the method name
 		 * is already taken.
 		 * is already taken.
 		 *
 		 *
-		 * It also pass {@link document.Document} and {@link document.Transaction} do the creator class.
+		 * It also passes {@link document.Document} and {@link document.Transaction} do the creator class.
 		 *
 		 *
-		 * Registered function returns `this` so they because chainable by default.
+		 * Registered function returns `this` so they can be chainable by default.
 		 *
 		 *
-		 * Beside that no magic happens here, the methods is added to the Transaction prototype.
+		 * Beside that no magic happens here, the method is added to the `Transaction` class prototype.
 		 *
 		 *
 		 * For example:
 		 * For example:
 		 *
 		 *

+ 2 - 3
packages/ckeditor5-engine/src/document/document.js

@@ -16,16 +16,15 @@ CKEDITOR.define( [
 	const graveyardSymbol = Symbol( 'graveyard' );
 	const graveyardSymbol = Symbol( 'graveyard' );
 
 
 	/**
 	/**
-	 * Document tree model describes all editable data in the editor. In may contains multiple {@link #roots root elements},
+	 * Document tree model describes all editable data in the editor. It may contain multiple {@link #roots root elements},
 	 * for example if the editor have multiple editable areas, each area will be represented by the separate root.
 	 * for example if the editor have multiple editable areas, each area will be represented by the separate root.
 	 *
 	 *
 	 * All changes in the document are done by {@link document.operation.Operation operations}. To create operations in
 	 * All changes in the document are done by {@link document.operation.Operation operations}. To create operations in
 	 * the simple way use use the {@link document.Transaction transaction} API, for example:
 	 * the simple way use use the {@link document.Transaction transaction} API, for example:
 	 *
 	 *
-	 *	  document.makeTransaction().insert( position, nodes ).split( otherPosition );
+	 *		document.makeTransaction().insert( position, nodes ).split( otherPosition );
 	 *
 	 *
 	 * @see #makeTransaction
 	 * @see #makeTransaction
-	 *
 	 * @class document.Document
 	 * @class document.Document
 	 */
 	 */
 	class Document {
 	class Document {

+ 1 - 1
packages/ckeditor5-engine/src/document/node.js

@@ -234,7 +234,7 @@ CKEDITOR.define( [ 'document/attribute', 'utils', 'ckeditorerror' ], ( Attribute
 		/**
 		/**
 		 * Returns attribute iterator. It can be use to create a new element with the same attributes:
 		 * Returns attribute iterator. It can be use to create a new element with the same attributes:
 		 *
 		 *
-		 *	  const copy = new Element( element.name, element.getAttrIterator() );
+		 *		const copy = new Element( element.name, element.getAttrIterator() );
 		 *
 		 *
 		 * @returns {Iterable.<document.Attribute>} Attribute iterator.
 		 * @returns {Iterable.<document.Attribute>} Attribute iterator.
 		 */
 		 */