浏览代码

Improved docs.

Piotrek Koszuliński 7 年之前
父节点
当前提交
9fb100ea7c

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

@@ -140,12 +140,12 @@ export default class DocumentSelection {
 	}
 
 	/**
-	 * Describes whether gravity is overridden (using {@link ~DocumentSelection#_overrideGravity}) or not.
+	 * Describes whether the gravity is overridden (using {@link module:engine/model/writer~Writer#overrideSelectionGravity}) or not.
 	 *
-	 * Note that gravity remains overridden as long as won't be restored the same number of times as was overridden.
+	 * Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden.
 	 *
 	 * @readonly
-	 * @return {boolean}
+	 * @return {Boolean}
 	 */
 	get isGravityOverridden() {
 		return this._selection.isGravityOverridden;

+ 14 - 12
packages/ckeditor5-engine/src/model/writer.js

@@ -1017,25 +1017,27 @@ export default class Writer {
 	}
 
 	/**
-	 * Temporarily changes the gravity of the selection from left to right. The gravity defines from which direction
-	 * the selection inherits its attributes. If it's the default left gravity, the selection (after being moved by
-	 * the user) inherits attributes from its left hand side. This method allows to temporarily override this behavior
-	 * by forcing the gravity to the right.
+	 * Temporarily changes the {@link module:engine/model/documentselection~DocumentSelection#isGravityOverridden gravity}
+	 * of the selection from left to right.
+	 *
+	 * The gravity defines from which direction the selection inherits its attributes. If it's the default left gravity,
+	 * then the selection (after being moved by the user) inherits attributes from its left-hand side.
+	 * This method allows to temporarily override this behavior by forcing the gravity to the right.
 	 *
 	 * For the following model fragment:
 	 *
-	 * 		<$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>
+	 *		<$text bold="true" linkHref="url">bar[]</$text><$text bold="true">biz</$text>
 	 *
-	 * Default gravity: selection will have the `bold` and `linkHref` attributes.
-	 * Overridden gravity: selection will have `bold` attribute.
+	 * * Default gravity: selection will have the `bold` and `linkHref` attributes.
+	 * * Overridden gravity: selection will have `bold` attribute.
 	 *
 	 * By default the selection's gravity is automatically restored just after a direct selection change (when user
-	 * move caret) but you can pass customRestore = true in which case you will have to call
+	 * moved the caret) but you can pass `customRestore = true` in which case you will have to call
 	 * {@link ~Writer#restoreSelectionGravity} manually.
 	 *
-	 * When the selection's gravity is overridden more than once without restoring meanwhile then needs to be restored
-	 * the same number of times as was overridden to revert default behavior. This is to prevent conflicts when
-	 * more than one feature want independently override and restore selection's gravity.
+	 * When the selection's gravity is overridden more than once without being restored in the meantime then it needs
+	 * to be restored the same number of times. This is to prevent conflicts when
+	 * more than one feature want to independently override and restore the selection's gravity.
 	 *
 	 * @param {Boolean} [customRestore=false] When `true` then gravity won't be restored until
 	 * {@link ~Writer#restoreSelectionGravity} will be called directly. When `false` then gravity is restored
@@ -1048,7 +1050,7 @@ export default class Writer {
 	/**
 	 * Restores {@link ~Writer#overrideSelectionGravity} gravity to default.
 	 *
-	 * Note that selection's gravity remains overridden as long as won't be restored the same number of times as was overridden.
+	 * Note that the gravity remains overridden as long as will not be restored the same number of times as it was overridden.
 	 */
 	restoreSelectionGravity() {
 		this.model.document.selection._restoreGravity();

+ 15 - 14
packages/ckeditor5-engine/src/utils/bindtwostepcarettoattribute.js

@@ -10,30 +10,31 @@
 import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
 
 /**
- * This helper adds two-steps caret movement behaviour for given attribute.
+ * This helper adds two-step caret movement behavior for the given attribute.
  *
- * When caret is moving by arrow keys and reach bound of text with attribute for which behaviour is enabled
- * then typing does not expand this attribute. Additional arrow key press is needed to "enter" to the text
- * and start typing with this attribute. The same is is for leaving this text.
+ * For example, when this behavior is enabled for the `linkHref` attribute (which converts to `<a>` element in the view)
+ * and the caret is just before an `<a>` element (at a link boundary), then pressing
+ * the right arrow key will move caret into that `<a>`element instead of moving it after the next character:
  *
- * When behaviour is enabled for `linkHref` attribute and caret is just before the attribute element then pressing
- * right arrow will move caret inside the attribute element instead of moving after next character:
+ * * With two-step caret movement: `<p>foo{}<a>bar</a>biz<p>` + <kbd>→</kbd> => `<p>foo<a>{}bar</a>biz<p>`
+ * * Without two-step caret movement: `<p>foo{}<a>bar</a>biz<p>` + <kbd>→</kbd> => `<p>foo<a>b{}ar</a>biz<p>`
  *
- * 		<p>foo{}<a>bar</a>biz<p> `->` <p>foo<a>{}foo</a>barr<p>
+ * The same behavior will be changed fo "leaving" an attribute element:
  *
- * The same is for "leaving" attribute element:
- *
- * 		<p>foo<a>bar{}</a>biz<p> `->` <p>foo<a>bar</a>{}biz<p>
+ * * With two-step caret movement: `<p>foo<a>bar{}</a>biz<p>` + <kbd>→</kbd> => `<p>foo<a>bar</a>{}biz<p>`
+ * * Without two-step caret movement: `<p>foo<a>bar{}</a>biz<p>` + <kbd>→</kbd> => `<p>foo<a>bar</a>b{}iz<p>`
  *
  * And when moving left:
  *
- * 		<p>foo<a>bar</a>{}biz<p> `<-` <p>foo<a>bar{}</a>biz<p>
- * 		<p>foo<a>{}bar</a>biz<p> `<-` <p>foo{}<a>bar</a>biz<p>
+ * * With two-step caret movement: `<p>foo<a>bar</a>b{}iz<p>` + <kbd>←</kbd> => `<p>foo<a>bar</a>{}biz<p>` +
+ * <kbd>←</kbd> => `<p>foo<a>bar{}</a>biz<p>`
+ * * Without two-step caret movement: `<p>foo<a>bar</a>b{}iz<p>` + <kbd>←</kbd> => `<p>foo<a>bar{}</a>biz<p>`
  *
  * @param {module:engine/view/view~View} view View controller instance.
  * @param {module:engine/model/model~Model} model Data model instance.
- * @param {module:utils/dom/emittermixin~Emitter} emitter The emitter to which this behavior should be added.
- * @param {String} attribute Attribute for which behaviour will be added.
+ * @param {module:utils/dom/emittermixin~Emitter} emitter The emitter to which this behavior should be added
+ * (e.g. a plugin instance).
+ * @param {String} attribute Attribute for which this behavior will be added.
  */
 export default function bindTwoStepCaretToAttribute( view, model, emitter, attribute ) {
 	const modelSelection = model.document.selection;