Browse Source

Document change event minor changes in docs and tests.

Szymon Cofalik 10 năm trước cách đây
mục cha
commit
0b0620b29b

+ 9 - 8
packages/ckeditor5-utils/src/document/document.js

@@ -165,19 +165,20 @@ CKEDITOR.define( [
 		 * * 'move' when nodes are moved,
 		 * * 'attr' when attributes change.
 		 *
-		 * Change event is fired after the change is done.
+		 * Change event is fired after the change is done. This means that any ranges or positions passed in
+		 * `changeInfo` are referencing nodes and paths in updated tree model.
 		 *
 		 * @event change
 		 * @param {String} type Change type, possible option: 'insert', 'remove', 'reinsert', 'move', 'attr'.
-		 * @param {Object} changeInfo Additional informations about the change.
+		 * @param {Object} changeInfo Additional information about the change.
 		 * @param {document.Range} changeInfo.range Range containing changed nodes. Note that for 'remove' the range will be in the
 		 * {@link #_graveyard graveyard root}.
-		 * @param {document.Range} [changeInfo.sourcePosition] Source position. For 'remove', 'reinsert' and 'move'. This property is
-		 * undefined for other node types. Note that for 'reinsert' the source position will be in the {@link #_graveyard graveyard root}.
-		 * @param {document.Attribute} [changeInfo.oldAttr] Only for 'attr' type. If the type is 'attr' and `oldAttr` is undefined it means
-		 * that new attribute was inserted. Otherwise it contains changed or removed attribute.
-		 * @param {document.Attribute} [changeInfo.newAttr] Only for 'attr' type. If the type is 'attr' and `newAttr` is undefined it means
-		 * that attribute was removed. Otherwise it contains changed or inserted attribute.
+		 * @param {document.Position} [changeInfo.sourcePosition] Change source position. Exists for 'remove', 'reinsert' and 'move'.
+		 * Note that for 'reinsert' the source position will be in the {@link #_graveyard graveyard root}.
+		 * @param {document.Attribute} [changeInfo.oldAttr] Only for 'attr' type. If the type is 'attr' and `oldAttr`
+		 * is `undefined` it means that new attribute was inserted. Otherwise it contains changed or removed attribute.
+		 * @param {document.Attribute} [changeInfo.newAttr] Only for 'attr' type. If the type is 'attr' and `newAttr`
+		 * is `undefined` it means that attribute was removed. Otherwise it contains changed or inserted attribute.
 		 */
 	}
 

+ 2 - 2
packages/ckeditor5-utils/src/document/operation/operation.js

@@ -70,8 +70,8 @@ CKEDITOR.define( [], () => {
 			 *
 			 * @protected
 			 * @method _execute
-			 * @returns {Object} Information about the change. It is always the range and additional informations depending on the
-			 * operation type.
+			 * @returns {Object} Object with additional information about the applied changes. Always has `range`
+			 * property containing changed nodes. May have additional properties depending on the operation type.
 			 */
 		}
 	}

+ 2 - 2
packages/ckeditor5-utils/tests/document/document.js

@@ -77,7 +77,7 @@ describe( 'Document', () => {
 	} );
 
 	describe( 'applyOperation', () => {
-		it( 'should increase document version and execute operation', () => {
+		it( 'should increase document version, execute operation and fire event with proper data', () => {
 			const changeCallback = sinon.spy();
 			const type = 't';
 			const data = { data: 'x' };
@@ -95,7 +95,7 @@ describe( 'Document', () => {
 			sinon.assert.calledOnce( operation._execute );
 
 			sinon.assert.calledOnce( changeCallback );
-			expect( changeCallback.args[ 0 ][ 1 ] ).to.equals( type );
+			expect( changeCallback.args[ 0 ][ 1 ] ).to.equal( type );
 			expect( changeCallback.args[ 0 ][ 2 ] ).to.equal( data );
 		} );