瀏覽代碼

Docs: Improved API docs.

Piotrek Koszuliński 7 年之前
父節點
當前提交
67b32ec911

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

@@ -26,8 +26,8 @@ const storePrefix = 'selection:';
  * {@link module:engine/model/document~Document#selection document's selection}.
  * There can be only one instance of `DocumentSelection` per document.
  *
- * All selection modifiers should be used from the {@link module:engine/model/writer~Writer} instance
- * inside the {@link module:engine/model/model~Model#change} block, as it provides a secure way to modify model.
+ * Document selection can only be changed by using the {@link module:engine/model/writer~Writer} instance
+ * inside the {@link module:engine/model/model~Model#change `change()`} block, as it provides a secure way to modify model.
  *
  * `DocumentSelection` is automatically updated upon changes in the {@link module:engine/model/document~Document document}
  * to always contain valid ranges. Its attributes are inherited from the text unless set explicitly.

+ 71 - 21
packages/ckeditor5-engine/src/model/model.js

@@ -28,12 +28,8 @@ import modifySelection from './utils/modifyselection';
 import getSelectedContent from './utils/getselectedcontent';
 
 /**
- * Editor's data model class. Model defines all the data: both nodes that are attached to the roots of the
- * {@link module:engine/model/model~Model#document model document}, and also all detached nodes which has not been yet
- * added to the document.
- *
- * All those nodes are created and modified by the {@link module:engine/model/writer~Writer model writer}, which can be
- * accessed by using {@link module:engine/model/model~Model#change} or {@link module:engine/model/model~Model#enqueueChange} methods.
+ * Editor's data model. Read about the model in the
+ * {@glink framework/guides/architecture/editing-engine engine architecture guide}.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */
@@ -146,8 +142,6 @@ export default class Model {
 	 *			return writer.createElement( 'img' );
 	 *		} );
 	 *
-	 * When the outermost block is done the {@link #event:_change} event is fired.
-	 *
 	 * @see #enqueueChange
 	 * @param {Function} callback Callback function which may modify the model.
 	 * @returns {*} Value returned by the callback.
@@ -165,7 +159,7 @@ export default class Model {
 	}
 
 	/**
-	 * `enqueueChange` method performs similar task as the {@link #change change method}, with two major differences.
+	 * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
 	 *
 	 * First, the callback of the `enqueueChange` is executed when all other changes are done. It might be executed
 	 * immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
@@ -243,20 +237,22 @@ export default class Model {
 	}
 
 	/**
-	 * See {@link module:engine/model/utils/insertcontent~insertContent}.
+	 * Inserts content into the editor (specified selection) as one would expect the paste
+	 * functionality to work.
 	 *
 	 * @fires insertContent
 	 * @param {module:engine/model/documentfragment~DocumentFragment|module:engine/model/item~Item} content The content to insert.
-	 * @param {module:engine/model/selection~Selection} selection Selection into which the content should be inserted.
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+	 * Selection into which the content should be inserted.
 	 */
 	insertContent( content, selection ) {
 		insertContent( this, content, selection );
 	}
 
 	/**
-	 * See {@link module:engine/model/utils/deletecontent.deleteContent}.
+	 * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
 	 *
-	 * Note: For the sake of predictability, the resulting selection should always be collapsed.
+	 * **Note:** For the sake of predictability, the resulting selection should always be collapsed.
 	 * In cases where a feature wants to modify deleting behavior so selection isn't collapsed
 	 * (e.g. a table feature may want to keep row selection after pressing <kbd>Backspace</kbd>),
 	 * then that behavior should be implemented in the view's listener. At the same time, the table feature
@@ -265,30 +261,84 @@ export default class Model {
 	 * That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables.
 	 *
 	 * @fires deleteContent
-	 * @param {module:engine/model/selection~Selection} selection Selection of which the content should be deleted.
-	 * @param {Object} options See {@link module:engine/model/utils/deletecontent~deleteContent}'s options.
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+	 * Selection of which the content should be deleted.
+	 * @param {module:engine/model/batch~Batch} batch Batch to which the deltas will be added.
+	 * @param {Object} [options]
+	 * @param {Boolean} [options.leaveUnmerged=false] Whether to merge elements after removing the content of the selection.
+	 *
+	 * For example `<heading>x[x</heading><paragraph>y]y</paragraph>` will become:
+	 *
+	 * * `<heading>x^y</heading>` with the option disabled (`leaveUnmerged == false`)
+	 * * `<heading>x^</heading><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
+	 *
+	 * Note: {@link module:engine/model/schema~Schema#isObject object} and {@link module:engine/model/schema~Schema#isLimit limit}
+	 * elements will not be merged.
+	 *
+	 * @param {Boolean} [options.doNotResetEntireContent=false] Whether to skip replacing the entire content with a
+	 * paragraph when the entire content was selected.
+	 *
+	 * For example `<heading>[x</heading><paragraph>y]</paragraph>` will become:
+	 *
+	 * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
+	 * * `<heading>^</heading>` with enabled (`doNotResetEntireContent == true`)
 	 */
 	deleteContent( selection, options ) {
 		deleteContent( this, selection, options );
 	}
 
 	/**
-	 * See {@link module:engine/model/utils/modifyselection~modifySelection}.
+	 * Modifies the selection. Currently, the supported modifications are:
+	 *
+	 * * Extending. The selection focus is moved in the specified `options.direction` with a step specified in `options.unit`.
+	 * Possible values for `unit` are:
+	 *  * `'character'` (default) - moves selection by one user-perceived character. In most cases this means moving by one
+	 *  character in `String` sense. However, unicode also defines "combing marks". These are special symbols, that combines
+	 *  with a symbol before it ("base character") to create one user-perceived character. For example, `q̣̇` is a normal
+	 *  letter `q` with two "combining marks": upper dot (`Ux0307`) and lower dot (`Ux0323`). For most actions, i.e. extending
+	 *  selection by one position, it is correct to include both "base character" and all of it's "combining marks". That is
+	 *  why `'character'` value is most natural and common method of modifying selection.
+	 *  * `'codePoint'` - moves selection by one unicode code point. In contrary to, `'character'` unit, this will insert
+	 *  selection between "base character" and "combining mark", because "combining marks" have their own unicode code points.
+	 *  However, for technical reasons, unicode code points with values above `UxFFFF` are represented in native `String` by
+	 *  two characters, called "surrogate pairs". Halves of "surrogate pairs" have a meaning only when placed next to each other.
+	 *  For example `𨭎` is represented in `String` by `\uD862\uDF4E`. Both `\uD862` and `\uDF4E` do not have any meaning
+	 *  outside the pair (are rendered as ? when alone). Position between them would be incorrect. In this case, selection
+	 *  extension will include whole "surrogate pair".
+	 *  * `'word'` - moves selection by a whole word.
+	 *
+	 * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
 	 *
 	 * @fires modifySelection
-	 * @param {module:engine/model/selection~Selection} selection The selection to modify.
-	 * @param {Object} options See {@link module:engine/model/utils/modifyselection.modifySelection}'s options.
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+	 * The selection to modify.
+	 * @param {Object} [options]
+	 * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
+	 * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
 	 */
 	modifySelection( selection, options ) {
 		modifySelection( this, selection, options );
 	}
 
 	/**
-	 * See {@link module:engine/model/utils/getselectedcontent~getSelectedContent}.
+	 * Gets a clone of the selected content.
+	 *
+	 * For example, for the following selection:
+	 *
+	 * ```html
+	 * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+	 * ```
+	 *
+	 * It will return a document fragment with such a content:
+	 *
+	 * ```html
+	 * <quote><h>st</h></quote><p>se</p>
+	 * ```
 	 *
 	 * @fires getSelectedContent
-	 * @param {module:engine/model/selection~Selection} selection The selection of which content will be retrieved.
-	 * @returns {module:engine/model/documentfragment~DocumentFragment} Document fragment holding the clone of the selected content.
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+	 * The selection of which content will be returned.
+	 * @returns {module:engine/model/documentfragment~DocumentFragment}
 	 */
 	getSelectedContent( selection ) {
 		return getSelectedContent( this, selection );

+ 6 - 1
packages/ckeditor5-engine/src/model/utils/deletecontent.js

@@ -15,6 +15,11 @@ import DocumentSelection from '../documentselection';
 /**
  * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
  *
+ * **Note:** Use {@link module:engine/model/model~Model#deleteContent} instead of this function.
+ * This function is only exposed to be reusable in algorithms
+ * which change the {@link module:engine/model/model~Model#deleteContent}
+ * method's behavior.
+ *
  * @param {module:engine/model/model~Model} model The model in context of which the insertion
  * should be performed.
  * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
@@ -34,7 +39,7 @@ import DocumentSelection from '../documentselection';
  * @param {Boolean} [options.doNotResetEntireContent=false] Whether to skip replacing the entire content with a
  * paragraph when the entire content was selected.
  *
- * For example `<heading>[x</heading><paragraph>y]</paragraph> will become:
+ * For example `<heading>[x</heading><paragraph>y]</paragraph>` will become:
  *
  * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
  * * `<heading>^</heading>` with enabled (`doNotResetEntireContent == true`).

+ 8 - 3
packages/ckeditor5-engine/src/model/utils/getselectedcontent.js

@@ -15,15 +15,20 @@ import Position from '../position';
  *
  * For example, for the following selection:
  *
- *		<p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+ * ```html
+ * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+ * ```
  *
  * It will return a document fragment with such a content:
  *
- *		<quote><h>st</h></quote><p>se</p>
+ * ```html
+ * <quote><h>st</h></quote><p>se</p>
+ * ```
  *
  * @param {module:engine/model/model~Model} model The model in context of which
  * the selection modification should be performed.
- * @param {module:engine/model/selection~Selection} selection The selection of which content will be returned.
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+ * The selection of which content will be returned.
  * @returns {module:engine/model/documentfragment~DocumentFragment}
  */
 export default function getSelectedContent( model, selection ) {

+ 7 - 1
packages/ckeditor5-engine/src/model/utils/modifyselection.js

@@ -37,9 +37,15 @@ const wordBoundaryCharacters = ' ,.?!:;"-()';
  *
  * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
  *
+ * **Note:** Use {@link module:engine/model/model~Model#modifySelection} instead of this function.
+ * This function is only exposed to be reusable in algorithms
+ * which change the {@link module:engine/model/model~Model#modifySelection}
+ * method's behavior.
+ *
  * @param {module:engine/model/model~Model} model The model in context of which
  * the selection modification should be performed.
- * @param {module:engine/model/selection~Selection} selection The selection to modify.
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+ * The selection to modify.
  * @param {Object} [options]
  * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
  * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.