Browse Source

Docs: Improved docs.

Szymon Cofalik 5 years ago
parent
commit
8027383e56

+ 1 - 1
docs/framework/guides/architecture/editing-engine.md

@@ -159,7 +159,7 @@ Markers are a special type of ranges.
 * They can only be created and changed through the {@link module:engine/model/writer~Writer model writer}.
 * They can be synchronized over the network with other collaborating clients.
 * They are automatically updated when the document's structure is changed.
-* They can be {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToHighlight converted to the editing view}, to show them in the editor.
+* They can be converted to the editing view, to show them in the editor (as {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToHighlight highlights} or {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToElement elements}).
 * They can be {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData converted to the data view}, to store them with the document data.
 * They can be {@link module:engine/conversion/upcasthelpers~UpcastHelpers#dataToMarker loaded with the document data}.
 

+ 6 - 0
packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -659,6 +659,12 @@ function shouldMarkerChangeBeConverted( modelPosition, marker, mapper ) {
  */
 
 /**
+ * The {@link module:engine/model/schema~Schema} instance set for the model that is downcast.
+ *
+ * @member {module:engine/model/schema~Schema} #schema
+ */
+
+/**
  * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate data during conversion.
  *
  * @member {module:engine/view/downcastwriter~DowncastWriter} #writer

+ 21 - 15
packages/ckeditor5-engine/src/conversion/downcasthelpers.js

@@ -368,24 +368,35 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 * and `name` attribute is added at that position,
 	 * * in other cases, a specified attribute is set on a view element that is before/after marker boundary.
 	 *
+	 * Typically, the marker names use `group:uniqueId:otherData` convention. For example: `comment:e34zfk9k2n459df53sjl34:zx32c`.
+	 * The default configuration for this conversion is that the first part is `group` part and the rest of
+	 * the marker name becomes `name` part.
+	 *
 	 * Tag and attribute names and values are generated from the marker name:
 	 *
-	 * * templates for attributes are `data-group-start-before="name"`, `data-group-start-after="name"`,
-	 * `data-group-end-before="name"` and `data-group-end-after="name"`,
-	 * * templates for view elements are `<group-start name="name">` and `<group-end name="name">`.
+	 * * templates for attributes are `data-[group]-start-before="[name]"`, `data-[group]-start-after="[name]"`,
+	 * `data-[group]-end-before="[name]"` and `data-[group]-end-after="[name]"`,
+	 * * templates for view elements are `<[group]-start name="[name]">` and `<[group]-end name="[name]">`.
 	 *
 	 * Attributes mark whether given marker start or end boundary is before or after given element.
-	 * Attributes `data-group-start-before` and `data-group-end-after` are favored. The other two are used when the former two cannot be used.
-	 *
-	 * Typically, the marker names use `group:uniqueId:otherData` convention. For example: `comment:e34zfk9k2n459df53sjl34:zx32c`.
-	 * The default configuration for this conversion is that the first part is `group` part and the rest of
-	 * the marker name becomes `name` part.
+	 * Attributes `data-[group]-start-before` and `data-[group]-end-after` are favored.
+	 * The other two are used when the former two cannot be used.
 	 *
 	 * The conversion configuration can take a function that will generate different group and name parts.
 	 * If such function is set as the `config.view` parameter, it is passed a marker name and it is expected to return an object with two
 	 * properties: `group` and `name`. If the function returns falsy value, the conversion will not take place.
 	 *
-	 * An example of a view that may be generated by this conversion:
+	 * Basic usage:
+	 *
+	 *		// Using the default conversion.
+	 *		// In this case, all markers which name starts with 'comment:' will be converted.
+	 *		// The `group` parameter will be set to `comment`.
+	 *		// The `name` parameter will be the rest of the marker name (without `:`).
+	 *		editor.conversion.for( 'dataDowncast' ).markerToData( {
+	 *			model: 'comment'
+	 *		} );
+	 *
+	 * An example of a view that may be generated by this conversion (assuming a marker with name `comment:commentId:uid` marked by `[]`):
 	 *
 	 *		// Model:
 	 *		<paragraph>Foo[bar</paragraph>
@@ -423,12 +434,7 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 * When there are multiple markers from the same group stored in the same attribute of the same element, their
 	 * name parts are put together in the attribute value, for example: `data-group-start-before="name1,name2,name3"`.
 	 *
-	 * Examples of usage:
-	 *
-	 *		// Using the default conversion:
-	 *		editor.conversion.for( 'dataDowncast' ).markerToData( {
-	 *			model: 'comment'
-	 *		} );
+	 * Other examples of usage:
 	 *
 	 *		// Using custom function which is the same as the default conversion:
 	 *		editor.conversion.for( 'dataDowncast' ).markerToData( {

+ 38 - 5
packages/ckeditor5-engine/src/conversion/upcasthelpers.js

@@ -9,6 +9,7 @@ import ConversionHelpers from './conversionhelpers';
 
 import { cloneDeep } from 'lodash-es';
 import ModelSelection from '../model/selection';
+import { attachLinkToDocumentation } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /* global console */
 
@@ -335,10 +336,20 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 * @returns {module:engine/conversion/upcasthelpers~UpcastHelpers}
 	 */
 	elementToMarker( config ) {
+		/**
+		 * The {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker `UpcastHelpers#elementToMarker()`}
+		 * method has been deprecated and will be removed in the near future.
+		 * Please use {@link module:engine/conversion/upcasthelpers~UpcastHelpers#dataToMarker `UpcastHelpers#dataToMarker()`} instead.
+		 *
+		 * @error upcast-helpers-element-to-marker-deprecated
+		 */
 		console.warn(
-			'upcast-helpers-element-to-marker-deprecated: ' +
-			'The UpcastHelpers#elementToMarker() method has been deprecated and will be removed in the near future. ' +
-			'Please use #dataToMarker() method instead.' );
+			attachLinkToDocumentation(
+				'upcast-helpers-element-to-marker-deprecated: ' +
+				'The UpcastHelpers#elementToMarker() method has been deprecated and will be removed in the near future. ' +
+				'Please use UpcastHelpers#dataToMarker() instead.'
+			)
+		);
 
 		return this.add( upcastElementToMarker( config ) );
 	}
@@ -346,10 +357,12 @@ export default class UpcastHelpers extends ConversionHelpers {
 	/**
 	 * View to model marker conversion helper.
 	 *
-	 * Converts view data created by {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} back to a model marker.
+	 * Converts view data created by {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`}
+	 * back to a model marker.
 	 *
 	 * This converter looks for specific view elements and view attributes that mark marker boundaries. See
-	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} to learn what view data is expected by this converter.
+	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} to learn what view data
+	 * is expected by this converter.
 	 *
 	 * The `config.view` property is equal to the marker group name to convert.
 	 *
@@ -359,11 +372,31 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 * If such function is set as the `config.model` parameter, it is passed the `name` part from the view element or attribute and it is
 	 * expected to return a string with the marker name.
 	 *
+	 * Basic usage:
+	 *
 	 *		// Using the default conversion.
+	 *		// In this case, all markers from `comment` group will be converted.
+	 *		// The conversion will look for `<comment-start>` and `<comment-end>` tags and
+	 *		// `data-comment-start-before`, `data-comment-start-after`,
+	 *		// `data-comment-end-before` and `data-comment-end-after` attributes.
 	 *		editor.conversion.for( 'upcast' ).dataToMarker( {
 	 *			view: 'comment'
 	 *		} );
 	 *
+	 * An example of a model that may be generated by this conversion:
+	 *
+	 *		// View:
+	 *		<p>Foo<comment-start name="commentId:uid"></comment-start>bar</p>
+	 *		<figure data-comment-end-after="commentId:uid" class="image"><img src="abc.jpg" /></figure>
+	 *
+	 *		// Model:
+	 *		<paragraph>Foo[bar</paragraph>
+	 *		<image src="abc.jpg"></image>]
+	 *
+	 * Where `[]` are boundaries of a marker that will receive `comment:commentId:uid` name.
+	 *
+	 * Other examples of usage:
+	 *
 	 *		// Using custom function which is the same as the default conversion:
 	 *		editor.conversion.for( 'upcast' ).dataToMarker( {
 	 *			view: 'comment',

+ 5 - 0
packages/ckeditor5-engine/src/model/markercollection.js

@@ -94,6 +94,11 @@ export default class MarkerCollection {
 		const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
 
 		if ( markerName.includes( ',' ) ) {
+			/**
+			 * Marker name cannot contain "," character.
+			 *
+			 * @error markercollection-incorrect-marker-name
+			 */
 			throw new CKEditorError( 'markercollection-incorrect-marker-name: Marker name cannot contain "," character.', this );
 		}