ソースを参照

Further API docs fixes. Removed YouTube movie replaced in balloon build example.

Anna Tomanek 5 年 前
コミット
60976a3854

+ 1 - 1
docs/_snippets/examples/balloon-editor.html

@@ -2,7 +2,7 @@
 	<h2>Walking the capitals of Europe: Warsaw</h2>
 
 	<figure class="media">
-		<oembed url="https://www.youtube.com/watch?v=WmWFwGLA1kQ"></oembed>
+		<oembed url="https://www.youtube.com/watch?v=7YRyFvjA_a8"></oembed>
 	</figure>
 
 	<p>If you enjoyed my previous articles in which we discussed wandering around <a href="https://en.wikipedia.org/wiki/Copenhagen">Copenhagen</a> and <a href="https://en.wikipedia.org/wiki/Vilnius">Vilnius</a>, you’ll definitely love exploring <a href="https://en.wikipedia.org/wiki/Warsaw">Warsaw</a>.</p>

+ 1 - 1
docs/framework/guides/tutorials/implementing-a-block-widget.md

@@ -22,7 +22,7 @@ While it is not strictly necessary to read the {@link framework/guides/quick-sta
 The tutorial will also reference various parts of the {@link framework/guides/architecture/intro CKEditor 5 architecture} section as you go. While reading them is not necessary to finish this tutorial, it is recommended to read these guides at some point to get a better understanding of the mechanisms used in this tutorial.
 
 <info-box>
-	If you want to use own event handler for events triggered by your widget then you must wrap it by a container that has a `data-cke-ignore-events` attribute to exclude it from editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
+	If you want to use your own event handler for events triggered by your widget, you must wrap it with a container that has a `data-cke-ignore-events` attribute to exclude it from the editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
 </info-box>
 
 ## Let's start

+ 1 - 1
docs/framework/guides/tutorials/using-react-in-a-widget.md

@@ -26,7 +26,7 @@ There are a couple of things you should know before you start:
 * Various parts of the {@link framework/guides/architecture/intro CKEditor 5 architecture} section will be referenced as you go. While reading them is not necessary to finish this tutorial, it is recommended to read those guides at some point to get a better understanding of the mechanisms used in this tutorial.
 
 <info-box>
-	If you want to use own event handler for events triggered by your React component then you must wrap it by a container that has a `data-cke-ignore-events` attribute to exclude it from editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
+	If you want to use your own event handler for events triggered by your React component, you must wrap it with a container that has a `data-cke-ignore-events` attribute to exclude it from the editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
 </info-box>
 
 ## Let's start

+ 42 - 42
packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -253,15 +253,15 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts a reconversion of an element. It will:
+	 * Starts the reconversion of an element. It will:
 	 *
-	 * * Fire a {@link #event:insert `insert` event} for the element to reconvert.
+	 * * Fire an {@link #event:insert `insert` event} for the element to reconvert.
 	 * * Fire an {@link #event:attribute `attribute` event} for element attributes.
 	 *
 	 * This will not reconvert children of the element if they have existing (already converted) views. For newly inserted child elements
 	 * it will behave the same as {@link #convertInsert}.
 	 *
-	 * Element reconversion is defined by a `triggerBy` configuration for
+	 * Element reconversion is defined by the `triggerBy` configuration for the
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
 	 * @fires insert
@@ -321,16 +321,16 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts model selection conversion.
+	 * Starts the model selection conversion.
 	 *
-	 * Fires events for given {@link module:engine/model/selection~Selection selection} to start selection conversion.
+	 * Fires events for a given {@link module:engine/model/selection~Selection selection} to start the selection conversion.
 	 *
 	 * @fires selection
 	 * @fires addMarker
 	 * @fires attribute
-	 * @param {module:engine/model/selection~Selection} selection Selection to convert.
-	 * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with converted model.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/selection~Selection} selection The selection to convert.
+	 * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with the converted model.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
 	 */
 	convertSelection( selection, markers, writer ) {
 		const markersAtSelection = Array.from( markers.getMarkersAtPosition( selection.getFirstPosition() ) );
@@ -381,13 +381,13 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Converts added marker. Fires {@link #event:addMarker addMarker} event for each item
-	 * in marker's range. If range is collapsed single event is dispatched. See event description for more details.
+	 * Converts the added marker. Fires the {@link #event:addMarker `addMarker`} event for each item
+	 * in the marker's range. If the range is collapsed, a single event is dispatched. See the event description for more details.
 	 *
 	 * @fires addMarker
 	 * @param {String} markerName Marker name.
-	 * @param {module:engine/model/range~Range} markerRange Marker range.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/range~Range} markerRange The marker range.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
 	 */
 	convertMarkerAdd( markerName, markerRange, writer ) {
 		// Do not convert if range is in graveyard or not in the document (e.g. in DocumentFragment).
@@ -437,12 +437,12 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Fires conversion of marker removal. Fires {@link #event:removeMarker removeMarker} event with provided data.
+	 * Fires the conversion of the marker removal. Fires the {@link #event:removeMarker `removeMarker`} event with the provided data.
 	 *
 	 * @fires removeMarker
 	 * @param {String} markerName Marker name.
-	 * @param {module:engine/model/range~Range} markerRange Marker range.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/range~Range} markerRange The marker range.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
 	 */
 	convertMarkerRemove( markerName, markerRange, writer ) {
 		// Do not convert if range is in graveyard or not in the document (e.g. in DocumentFragment).
@@ -458,31 +458,31 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Maps model element "insert" reconversion for given event names. The event names must be fully specified:
+	 * Maps the model element "insert" reconversion for given event names. The event names must be fully specified:
 	 *
-	 * * For "attribute" change event it should include main element name, ie: `'attribute:attributeName:elementName'`.
-	 * * For child nodes change events, those should use child event name as well, ie:
+	 * * For "attribute" change event, it should include the main element name, i.e: `'attribute:attributeName:elementName'`.
+	 * * For child node change events, these should use the child event name as well, i.e:
 	 *     * For adding a node: `'insert:childElementName'`.
 	 *     * For removing a node: `'remove:childElementName'`.
 	 *
-	 * **Note**: This method should not be used directly. A reconversion is defined by `triggerBy` configuration of the `elementToElement()`
-	 * conversion helper.
+	 * **Note**: This method should not be used directly. The reconversion is defined by the `triggerBy()` configuration of the
+	 * `elementToElement()` conversion helper.
 	 *
 	 * @protected
-	 * @param {String} modelName Main model element name for which events will trigger reconversion.
-	 * @param {String} eventName Name of an event that would trigger conversion for given model element.
+	 * @param {String} modelName The name of the main model element for which the events will trigger the reconversion.
+	 * @param {String} eventName The name of an event that would trigger conversion for a given model element.
 	 */
 	_mapReconversionTriggerEvent( modelName, eventName ) {
 		this._reconversionEventsMapping.set( eventName, modelName );
 	}
 
 	/**
-	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume from given range,
+	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume from a given range,
 	 * assuming that the range has just been inserted to the model.
 	 *
 	 * @private
-	 * @param {module:engine/model/range~Range} range Inserted range.
-	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} Values to consume.
+	 * @param {module:engine/model/range~Range} range The inserted range.
+	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
 	 */
 	_createInsertConsumable( range ) {
 		const consumable = new Consumable();
@@ -501,12 +501,12 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume for given range.
+	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume for a given range.
 	 *
 	 * @private
-	 * @param {module:engine/model/range~Range} range Affected range.
+	 * @param {module:engine/model/range~Range} range The affected range.
 	 * @param {String} type Consumable type.
-	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} Values to consume.
+	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
 	 */
 	_createConsumableForRange( range, type ) {
 		const consumable = new Consumable();
@@ -522,9 +522,9 @@ export default class DowncastDispatcher {
 	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with selection consumable values.
 	 *
 	 * @private
-	 * @param {module:engine/model/selection~Selection} selection Selection to create consumable from.
-	 * @param {Iterable.<module:engine/model/markercollection~Marker>} markers Markers which contains selection.
-	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} Values to consume.
+	 * @param {module:engine/model/selection~Selection} selection The selection to create the consumable from.
+	 * @param {Iterable.<module:engine/model/markercollection~Marker>} markers Markers that contain the selection.
+	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
 	 */
 	_createSelectionConsumable( selection, markers ) {
 		const consumable = new Consumable();
@@ -561,7 +561,7 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Clears conversion API object.
+	 * Clears the conversion API object.
 	 *
 	 * @private
 	 */
@@ -571,7 +571,7 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Internal method for converting element insert. It will fire events for the inserted element and events for its attributes.
+	 * Internal method for converting element insertion. It will fire events for the inserted element and events for its attributes.
 	 *
 	 * @private
 	 * @fires insert
@@ -594,13 +594,13 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Returns differ changes together with added "reconvert" type changes for {@link #reconvertElement}. Those are defined by
-	 * a `triggerBy` configuration for
+	 * Returns differ changes together with added "reconvert" type changes for {@link #reconvertElement}. These are defined by
+	 * a the `triggerBy()` configuration for the
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
-	 * This method will remove every mapped insert or remove change with a single "reconvert" changes.
+	 * This method will remove every mapped insert or remove change with a single "reconvert" change.
 	 *
-	 * For instance: Having a `triggerBy` configuration defined for `<complex>` element that issues this element reconversion on
+	 * For instance: Having a `triggerBy()` configuration defined for the `<complex>` element that issues this element reconversion on
 	 * `foo` and `bar` attributes change, and a set of changes for this element:
 	 *
 	 *		const differChanges = [
@@ -616,7 +616,7 @@ export default class DowncastDispatcher {
 	 *			{ type: 'attribute', attributeKey: 'baz', ... }
 	 *		];
 	 *
-	 * In the example above the `'baz'` attribute change will fire an {@link #event:attribute attribute event}
+	 * In the example above, the `'baz'` attribute change will fire an {@link #event:attribute attribute event}
 	 *
 	 * @param {module:engine/model/differ~Differ} differ The differ object with buffered changes.
 	 * @returns {Array.<Object>} Updated set of changes.
@@ -676,14 +676,14 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Checks if resulting change should trigger element reconversion.
+	 * Checks if the resulting change should trigger element reconversion.
 	 *
-	 * Those are defined by a `triggerBy` configuration for
+	 * These are defined by a `triggerBy()` configuration for the
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
 	 * @private
-	 * @param {String} eventName Event name to check.
-	 * @param {String} elementName Element name to check.
+	 * @param {String} eventName The event name to check.
+	 * @param {String} elementName The element name to check.
 	 * @returns {Boolean}
 	 */
 	_isReconvertTriggerEvent( eventName, elementName ) {

+ 8 - 6
packages/ckeditor5-engine/src/conversion/downcasthelpers.js

@@ -59,9 +59,9 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *			}
 	 *		} );
 	 *
-	 * The element-to-element conversion supports a reconversion mechanism. This is helpful in conversion to complex view structures where
-	 * multiple atomic element-to-element and attribute-to-attribute or attribute-to-element could be used. By specifying `triggerBy`
-	 * events you can trigger reconverting model to a full view tree structures at once.
+	 * The element-to-element conversion supports the reconversion mechanism. This is helpful in the conversion to complex view structures
+	 * where multiple atomic element-to-element and attribute-to-attribute or attribute-to-element could be used. By specifying
+	 * `triggerBy()` events you can trigger reconverting the model to full view tree structures at once.
 	 *
 	 *		editor.conversion.for( 'downcast' ).elementToElement( {
 	 *			model: 'complex',
@@ -84,9 +84,11 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view A view element definition or a function
 	 * that takes the model element and {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi downcast conversion API}
 	 * as parameters and returns a view container element.
-	 * @param {Object} [config.triggerBy] Re-conversion triggers. At least one trigger must be defined.
-	 * @param {Array.<String>} config.triggerBy.attributes Name of element's attributes which change will trigger element reconversion.
-	 * @param {Array.<String>} config.triggerBy.children Name of direct children that adding or removing will trigger element reconversion.
+	 * @param {Object} [config.triggerBy] Reconversion triggers. At least one trigger must be defined.
+	 * @param {Array.<String>} config.triggerBy.attributes The name of the element's attributes whose change will trigger element
+	 * reconversion.
+	 * @param {Array.<String>} config.triggerBy.children The name of direct children whose adding or removing will trigger element
+	 * reconversion.
 	 * @returns {module:engine/conversion/downcasthelpers~DowncastHelpers}
 	 */
 	elementToElement( config ) {

+ 2 - 2
packages/ckeditor5-engine/src/view/observer/observer.js

@@ -83,7 +83,7 @@ export default class Observer {
 	}
 
 	/**
-	 * Checks whether the given DOM event should be ignored (should not be turned into a synthetic view document event).
+	 * Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).
 	 *
 	 * Currently, an event will be ignored only if its target or any of its ancestors has the `data-cke-ignore-events` attribute.
 	 * This attribute can be used inside the structures generated by
@@ -91,7 +91,7 @@ export default class Observer {
 	 * fired within a UI that should be excluded from CKEditor 5's realms.
 	 *
 	 * @param {Node} domTarget The DOM event target to check (usually an element, sometimes a text node and
-	 * potentially sometimes a document too).
+	 * potentially sometimes a document, too).
 	 * @returns {Boolean} Whether this event should be ignored by the observer.
 	 */
 	checkShouldIgnoreEventFromTarget( domTarget ) {

+ 1 - 1
packages/ckeditor5-html-embed/README.md

@@ -5,7 +5,7 @@ CKEditor 5 HTML embed feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-html-embed/status.svg)](https://david-dm.org/ckeditor/ckeditor5-html-embed)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-html-embed/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-html-embed?type=dev)
 
-This package implements the HTML embed feature for CKEditor 5.
+This package implements the HTML embed feature for CKEditor 5. It allows embedding an arbitrary HTML snippet in the rich-text editor.
 
 ## Demo
 

+ 5 - 5
packages/ckeditor5-link/src/utils.js

@@ -35,7 +35,7 @@ export function isLinkElement( node ) {
 }
 
 /**
- * Creates link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
+ * Creates a link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
  *
  * @param {String} href
  * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi
@@ -154,11 +154,11 @@ export function isEmail( value ) {
 }
 
 /**
- * Adds protocol prefix to the specified `link` when:
+ * Adds the protocol prefix to the specified `link` when:
  *
- * * it doesn't contain it already, and there is a {@link module:link/link~LinkConfig#defaultProtocol `defaultProtocol` }
- * config value provided
- * * or the link is an email address
+ * * it does not contain it already, and there is a {@link module:link/link~LinkConfig#defaultProtocol `defaultProtocol` }
+ * configuration value provided,
+ * * or the link is an email address.
  *
  *
  * @params {String} link

+ 4 - 4
packages/ckeditor5-utils/src/ckeditorerror.js

@@ -140,7 +140,7 @@ export default class CKEditorError extends Error {
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to throw an error and when to log
  * a warning or an error to the console.
  *
- * @param {String} errorName Error name to be logged.
+ * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
  * @returns {String}
  */
@@ -149,8 +149,8 @@ export function logWarning( errorName, data ) {
 }
 
 /**
- * Logs an error to the console with properly formatted message and adds a link to the documentation.
- * Use whenever you want to log a error to the console.
+ * Logs an error to the console with a properly formatted message and adds a link to the documentation.
+ * Use whenever you want to log an error to the console.
  *
  *		/**
  *		 * There was a problem processing the configuration of the toolbar. The item with the given
@@ -165,7 +165,7 @@ export function logWarning( errorName, data ) {
  *
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to use each method.
  *
- * @param {String} errorName Error name to be logged.
+ * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
  * @returns {String}
  */