瀏覽代碼

More error documentation improvements.

Piotrek Koszuliński 8 年之前
父節點
當前提交
2794b867aa

+ 2 - 2
packages/ckeditor5-engine/src/conversion/buildmodelconverter.js

@@ -315,12 +315,12 @@ class ModelConverterBuilder {
 
 		if ( this._from.type != 'marker' ) {
 			/**
-			 * To highlight conversion is supported only for model markers.
+			 * Conversion to a highlight is supported only from model markers.
 			 *
 			 * @error build-model-converter-non-marker-to-highlight
 			 */
 			throw new CKEditorError(
-				'build-model-converter-non-marker-to-highlight: Conversion to highlight is supported ' +
+				'build-model-converter-non-marker-to-highlight: Conversion to a highlight is supported ' +
 				'only from model markers.'
 			);
 		}

+ 10 - 1
packages/ckeditor5-engine/src/conversion/viewconsumable.js

@@ -490,7 +490,16 @@ class ViewElementConsumables {
 		for ( const name of items ) {
 			if ( type === 'attribute' && ( name === 'class' || name === 'style' ) ) {
 				/**
-				 * Class and style attributes should be handled separately.
+				 * Class and style attributes should be handled separately in
+				 * {@link module:engine/conversion/viewconsumable~ViewConsumable#add `ViewConsumable#add()`}.
+				 *
+				 * What you have done is trying to use:
+				 *
+				 *		consumables.add( { attribute: [ 'class', 'style' ] } );
+				 *
+				 * While each class and style should be registered separately:
+				 *
+				 *		consumables.add( { class: 'some-class', style: 'font-weight' } );
 				 *
 				 * @error viewconsumable-invalid-attribute
 				 */

+ 2 - 2
packages/ckeditor5-engine/src/conversion/viewconversiondispatcher.js

@@ -184,14 +184,14 @@ export default class ViewConversionDispatcher {
 		// Handle incorrect `data.output`.
 		if ( data.output && !( data.output instanceof ModelNode || data.output instanceof ModelDocumentFragment ) ) {
 			/**
-			 * Dropped incorrect conversion result.
+			 * Incorrect conversion result was dropped.
 			 *
 			 * Item may be converted to either {@link module:engine/model/node~Node model node} or
 			 * {@link module:engine/model/documentfragment~DocumentFragment model document fragment}.
 			 *
 			 * @error view-conversion-dispatcher-incorrect-result
 			 */
-			log.warn( 'view-conversion-dispatcher-incorrect-result: Dropped incorrect conversion result.', [ input, data.output ] );
+			log.warn( 'view-conversion-dispatcher-incorrect-result: Incorrect conversion result was dropped.', [ input, data.output ] );
 
 			return null;
 		}

+ 2 - 2
packages/ckeditor5-engine/src/model/delta/markerdelta.js

@@ -103,11 +103,11 @@ register( 'removeMarker', function( markerOrName ) {
 
 	if ( !this.document.markers.has( name ) ) {
 		/**
-		 * Trying to remove marker that does not exist.
+		 * Trying to remove marker which does not exist.
 		 *
 		 * @error batch-removeMarker-no-marker
 		 */
-		throw new CKEditorError( 'batch-removeMarker-no-marker: Trying to remove marker that does not exist.' );
+		throw new CKEditorError( 'batch-removeMarker-no-marker: Trying to remove marker which does not exist.' );
 	}
 
 	const oldRange = this.document.markers.get( name ).getRange();

+ 2 - 1
packages/ckeditor5-engine/src/model/document.js

@@ -116,7 +116,8 @@ export default class Document {
 			for ( const range of this.selection.getRanges() ) {
 				if ( !this._validateSelectionRange( range ) ) {
 					/**
-					 * Range from document selection starts or ends at incorrect position.
+					 * Range from {@link module:engine/model/documentselection~DocumentSelection document selection}
+					 * starts or ends at incorrect position.
 					 *
 					 * @error document-selection-wrong-position
 					 * @param {module:engine/model/range~Range} range

+ 3 - 1
packages/ckeditor5-engine/src/model/documentselection.js

@@ -262,13 +262,15 @@ export default class DocumentSelection extends Selection {
 	 */
 	static createFromSelection() {
 		/**
+		 * Cannot create a new `DocumentSelection` instance.
+		 *
 		 * `DocumentSelection#createFromSelection()` is not available. There can be only one
 		 * `DocumentSelection` per document instance, so creating new `DocumentSelection`s this way
 		 * would be unsafe.
 		 *
 		 * @error documentselection-cannot-create
 		 */
-		throw new CKEditorError( 'documentselection-cannot-create: Cannot create new DocumentSelection instance.' );
+		throw new CKEditorError( 'documentselection-cannot-create: Cannot create a new DocumentSelection instance.' );
 	}
 
 	/**

+ 4 - 2
packages/ckeditor5-engine/src/model/liveposition.js

@@ -43,11 +43,13 @@ export default class LivePosition extends Position {
 
 		if ( !this.root.is( 'rootElement' ) ) {
 			/**
-			 * LivePosition root has to be an instance of RootElement.
+			 * LivePosition's root has to be an instance of RootElement.
 			 *
 			 * @error liveposition-root-not-rootelement
 			 */
-			throw new CKEditorError( 'model-liveposition-root-not-rootelement: LivePosition root has to be an instance of RootElement.' );
+			throw new CKEditorError(
+				'model-liveposition-root-not-rootelement: LivePosition\'s root has to be an instance of RootElement.'
+			);
 		}
 
 		/**

+ 7 - 7
packages/ckeditor5-engine/src/model/markercollection.js

@@ -142,7 +142,7 @@ export default class MarkerCollection {
 	}
 
 	/**
-	 * Destroys markers collection.
+	 * Destroys marker collection and all markers inside it.
 	 */
 	destroy() {
 		for ( const marker of this._markers.values() ) {
@@ -176,7 +176,7 @@ export default class MarkerCollection {
 	}
 
 	/**
-	 * Destroys marker.
+	 * Destroys the marker.
 	 *
 	 * @private
 	 * @param {module:engine/model/markercollection~Marker} marker Marker to destroy.
@@ -241,7 +241,7 @@ class Marker {
 	 */
 	constructor( name, liveRange ) {
 		/**
-		 * Marker name.
+		 * Marker's name.
 		 *
 		 * @readonly
 		 * @member {String} #name
@@ -268,7 +268,7 @@ class Marker {
 	 */
 	getStart() {
 		if ( !this._liveRange ) {
-			throw new CKEditorError( 'marker-destroyed: Operating on destroyed marker instance.' );
+			throw new CKEditorError( 'marker-destroyed: Cannot use a destroyed marker instance.' );
 		}
 
 		return Position.createFromPosition( this._liveRange.start );
@@ -281,7 +281,7 @@ class Marker {
 	 */
 	getEnd() {
 		if ( !this._liveRange ) {
-			throw new CKEditorError( 'marker-destroyed: Operating on destroyed marker instance.' );
+			throw new CKEditorError( 'marker-destroyed: Cannot use a destroyed marker instance.' );
 		}
 
 		return Position.createFromPosition( this._liveRange.end );
@@ -301,7 +301,7 @@ class Marker {
 	 */
 	getRange() {
 		if ( !this._liveRange ) {
-			throw new CKEditorError( 'marker-destroyed: Operating on destroyed marker instance.' );
+			throw new CKEditorError( 'marker-destroyed: Cannot use a destroyed marker instance.' );
 		}
 
 		return Range.createFromRange( this._liveRange );
@@ -339,7 +339,7 @@ class Marker {
 mix( Marker, EmitterMixin );
 
 /**
- * Operating on destroyed marker instance.
+ * Cannot use a {@link module:engine/model/markercollection~MarkerCollection#destroy destroyed marker} instance.
  *
  * @error marker-destroyed
  */

+ 2 - 0
packages/ckeditor5-engine/src/model/node.js

@@ -405,5 +405,7 @@ export default class Node {
 /**
  * The node's parent does not contain this node.
  *
+ * This error may be thrown from corrupted trees.
+ *
  * @error model-node-not-found-in-parent
  */

+ 7 - 5
packages/ckeditor5-engine/src/model/position.js

@@ -45,7 +45,9 @@ export default class Position {
 	constructor( root, path ) {
 		if ( !root.is( 'element' ) && !root.is( 'documentFragment' ) ) {
 			/**
-			 * Position root invalid.
+			 * Position root is invalid.
+			 *
+			 * Positions can only be anchored in elements or document fragments.
 			 *
 			 * @error model-position-root-invalid
 			 */
@@ -54,12 +56,12 @@ export default class Position {
 
 		if ( !( path instanceof Array ) || path.length === 0 ) {
 			/**
-			 * Position path must be an Array with at least one item.
+			 * Position path must be an array with at least one item.
 			 *
 			 * @error model-position-path-incorrect
 			 * @param path
 			 */
-			throw new CKEditorError( 'model-position-path-incorrect: Position path must be an Array with at least one item.', { path } );
+			throw new CKEditorError( 'model-position-path-incorrect: Position path must be an array with at least one item.', { path } );
 		}
 
 		// Normalize the root and path (if element was passed).
@@ -686,7 +688,7 @@ export default class Position {
 	static createAfter( item ) {
 		if ( !item.parent ) {
 			/**
-			 * You can not make position after root.
+			 * You can not make a position after a root element.
 			 *
 			 * @error model-position-after-root
 			 * @param {module:engine/model/item~Item} root
@@ -706,7 +708,7 @@ export default class Position {
 	static createBefore( item ) {
 		if ( !item.parent ) {
 			/**
-			 * You can not make position before root.
+			 * You can not make a position before a root element.
 			 *
 			 * @error model-position-before-root
 			 * @param {module:engine/model/item~Item} root

+ 2 - 1
packages/ckeditor5-engine/src/model/range.js

@@ -778,7 +778,8 @@ export default class Range {
 	static createFromRanges( ranges ) {
 		if ( ranges.length === 0 ) {
 			/**
-			 * At least one range has to be passed.
+			 * At least one range has to be passed to
+			 * {@link module:engine/model/range~Range.createFromRanges `Range.createFromRanges()`}.
 			 *
 			 * @error range-create-from-ranges-empty-array
 			 */

+ 2 - 2
packages/ckeditor5-engine/src/model/textproxy.js

@@ -60,7 +60,7 @@ export default class TextProxy {
 
 		if ( offsetInText < 0 || offsetInText > textNode.offsetSize ) {
 			/**
-			 * Given offsetInText value is incorrect.
+			 * Given `offsetInText` value is incorrect.
 			 *
 			 * @error model-textproxy-wrong-offsetintext
 			 */
@@ -69,7 +69,7 @@ export default class TextProxy {
 
 		if ( length < 0 || offsetInText + length > textNode.offsetSize ) {
 			/**
-			 * Given length value is incorrect.
+			 * Given `length` value is incorrect.
 			 *
 			 * @error model-textproxy-wrong-length
 			 */

+ 1 - 1
packages/ckeditor5-engine/src/model/treewalker.js

@@ -38,7 +38,7 @@ export default class TreeWalker {
 	constructor( options = {} ) {
 		if ( !options.boundaries && !options.startPosition ) {
 			/**
-			 * Neither boundaries nor starting position have been defined.
+			 * Neither boundaries nor starting position of a `TreeWalker` have been defined.
 			 *
 			 * @error model-tree-walker-no-start-position
 			 */

+ 4 - 4
packages/ckeditor5-engine/src/model/writer.js

@@ -82,12 +82,12 @@ export function insert( position, nodes ) {
 export function remove( range ) {
 	if ( !range.isFlat ) {
 		/**
-		 * Trying to remove a range that starts and ends in different element.
+		 * Trying to remove a range which starts and ends in different element.
 		 *
 		 * @error model-writer-remove-range-not-flat
 		 */
 		throw new CKEditorError( 'model-writer-remove-range-not-flat: ' +
-			'Trying to remove a range that starts and ends in different element.' );
+			'Trying to remove a range which starts and ends in different element.' );
 	}
 
 	const parent = range.start.parent;
@@ -116,12 +116,12 @@ export function remove( range ) {
 export function move( sourceRange, targetPosition ) {
 	if ( !sourceRange.isFlat ) {
 		/**
-		 * Trying to move a range that starts and ends in different element.
+		 * Trying to move a range which starts and ends in different element.
 		 *
 		 * @error model-writer-move-range-not-flat
 		 */
 		throw new CKEditorError( 'model-writer-move-range-not-flat: ' +
-			'Trying to move a range that starts and ends in different element.' );
+			'Trying to move a range which starts and ends in different element.' );
 	}
 
 	const nodes = this.remove( sourceRange );