Przeglądaj źródła

Docs: Various API docs improvements.

Piotrek Koszuliński 7 lat temu
rodzic
commit
f7c71cae6d

+ 10 - 4
packages/ckeditor5-engine/src/model/differ.js

@@ -111,7 +111,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Buffers a given operation. An operation has to be buffered before it is executed.
+	 * Buffers the given operation. An operation has to be buffered before it is executed.
 	 *
 	 * Operation type is checked and it is checked which nodes it will affect. These nodes are then stored in `Differ`
 	 * in the state before the operation is executed.
@@ -183,7 +183,7 @@ export default class Differ {
 	}
 
 	/**
-	 * Buffers marker change.
+	 * Buffers a marker change.
 	 *
 	 * @param {String} markerName The name of the marker that changed.
 	 * @param {module:engine/model/range~Range|null} oldRange Marker range before the change or `null` if the marker has just
@@ -247,9 +247,15 @@ export default class Differ {
 	}
 
 	/**
-	 * Checks whether some of buffered marker affects the editor data or whether some element changed.
+	 * Checks whether some of the buffered changes affect the editor data.
 	 *
-	 * @returns {Boolean} `true` if buffered markers or changes in elements affects the editor data.
+	 * Types of changes which affect the editor data:
+	 *
+	 * * model structure changes,
+	 * * attribute changes,
+	 * * changes of markers which were defined as `affectingData`.
+	 *
+	 * @returns {Boolean}
 	 */
 	hasDataChanges() {
 		for ( const [ , change ] of this._changedMarkers ) {

+ 20 - 8
packages/ckeditor5-engine/src/model/document.js

@@ -23,9 +23,18 @@ import { isInsideSurrogatePair, isInsideCombinedSymbol } from '@ckeditor/ckedito
 const graveyardName = '$graveyard';
 
 /**
- * Document tree model describes all editable data in the editor. It may contain multiple
- * {@link module:engine/model/document~Document#roots root elements}. For example, if the editor has multiple editable areas,
- * each area will be represented by a separate root.
+ * Data model's document. It contains the model's structure, its selection and the history of changes.
+ *
+ * Read more about working with the model in
+ * {@glink framework/guides/architecture/editing-engine#model introduction to the the editing engine's architecture}.
+ *
+ * Usually, the document contains just one {@link module:engine/model/document~Document#roots root element}, so
+ * you can retrieve it by just calling {@link module:engine/model/document~Document#getRoot} without specifying its name:
+ *
+ *		model.document.getRoot(); // -> returns the main root
+ *
+ * However, the document may contain multiple roots – e.g. when the editor has multiple editable areas
+ * (e.g. a title and a body of a message).
  *
  * @mixes module:utils/emittermixin~EmitterMixin
  */
@@ -46,6 +55,7 @@ export default class Document {
 		/**
 		 * The document version. It starts from `0` and every operation increases the version number. It is used to ensure that
 		 * operations are applied on a proper document version.
+		 *
 		 * If the {@link module:engine/model/operation/operation~Operation#baseVersion base version} does not match the document version,
 		 * a {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown.
 		 *
@@ -65,7 +75,7 @@ export default class Document {
 		this.history = new History( this );
 
 		/**
-		 * The selection done on this document.
+		 * The selection in this document.
 		 *
 		 * @readonly
 		 * @member {module:engine/model/documentselection~DocumentSelection}
@@ -381,12 +391,12 @@ export default class Document {
 	 * If you want to be notified about all these changes, then simply listen to this event like this:
 	 *
 	 *		model.document.on( 'change', () => {
-	 *			console.log( 'The Document has changed!' );
+	 *			console.log( 'The document has changed!' );
 	 *		} );
 	 *
 	 * If, however, you only want to be notified about the data changes, then use the
 	 * {@link module:engine/model/document~Document#event:change:data change:data} event,
-	 * which fires for document structure changes and marker changes (which affects the data).
+	 * which is fired for document structure changes and marker changes (which affects the data).
 	 *
 	 *		model.document.on( 'change:data', () => {
 	 *			console.log( 'The data has changed!' );
@@ -397,7 +407,9 @@ export default class Document {
 	 */
 
 	/**
-	 * Fired when the data changes, which includes:
+	 * It is a narrower version of the {@link #event:change} event. It is fired for changes which
+	 * affect the editor data. This is:
+	 *
 	 * * document structure changes,
 	 * * marker changes (which affects the data).
 	 *
@@ -407,7 +419,7 @@ export default class Document {
 	 *			console.log( 'The data has changed!' );
 	 *		} );
 	 *
-	 * If you would like to listen to all document's changes, then look at the
+	 * If you would like to listen to all document changes, then check out the
 	 * {@link module:engine/model/document~Document#event:change change} event.
 	 *
 	 * @event change:data

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

@@ -795,7 +795,8 @@ export default class Writer {
 	 * markers managed by operations and not-managed by operations.
 	 *
 	 * The `options.affectsData` parameter, which defaults to `false`, allows you to define if a marker affects the data. It should be
-	 * `true` when the marker change changes the data returned by {@link module:core/editor/editor~Editor#getData} method.
+	 * `true` when the marker change changes the data returned by the
+	 * {@link module:core/editor/utils/dataapimixin~DataApi#getData `editor.getData()`} method.
 	 * When set to `true` it fires the {@link module:engine/model/document~Document#event:change:data `change:data`} event.
 	 * When set to `false` it fires the {@link module:engine/model/document~Document#event:change `change`} event.
 	 *
@@ -880,7 +881,8 @@ export default class Writer {
 	 * markers managed by operations and not-managed by operations. It is possible to change this option for an existing marker.
 	 *
 	 * The `options.affectsData` parameter, which defaults to `false`, allows you to define if a marker affects the data. It should be
-	 * `true` when the marker change changes the data returned by {@link module:core/editor/editor~Editor#getData} method.
+	 * `true` when the marker change changes the data returned by
+	 * the {@link module:core/editor/utils/dataapimixin~DataApi#getData `editor.getData()`} method.
 	 * When set to `true` it fires the {@link module:engine/model/document~Document#event:change:data `change:data`} event.
 	 * When set to `false` it fires the {@link module:engine/model/document~Document#event:change `change`} event.
 	 *