浏览代码

Docs: release api review, batch 2.

godai78 5 年之前
父节点
当前提交
2591a6574f

+ 12 - 12
packages/ckeditor5-core/src/plugincollection.js

@@ -21,11 +21,11 @@ export default class PluginCollection {
 	/**
 	 * Creates an instance of the plugin collection class.
 	 * Allows loading and initializing plugins and their dependencies.
-	 * Allows to provide a list of already loaded plugins. These plugins will not be destroyed along with this collection.
+	 * Allows providing a list of already loaded plugins. These plugins will not be destroyed along with this collection.
 	 *
 	 * @param {module:core/editor/editor~Editor|module:core/context~Context} context
 	 * @param {Array.<Function>} [availablePlugins] Plugins (constructors) which the collection will be able to use
-	 * when {@link module:core/plugincollection~PluginCollection#init} is used with plugin names (strings, instead of constructors).
+	 * when {@link module:core/plugincollection~PluginCollection#init} is used with the plugin names (strings, instead of constructors).
 	 * Usually, the editor will pass its built-in plugins to the collection so they can later be
 	 * used in `config.plugins` or `config.removePlugins` by names.
 	 * @param {Iterable.<Array>} contextPlugins A list of already initialized plugins represented by a
@@ -105,8 +105,8 @@ export default class PluginCollection {
 	 *			} );
 	 *		}
 	 *
-	 * **Note**: This method will throw error if plugin is not loaded. Use `{@link #has editor.plugins.has()}`
-	 * to check if plugin is available.
+	 * **Note**: This method will throw an error if a plugin is not loaded. Use `{@link #has editor.plugins.has()}`
+	 * to check if a plugin is available.
 	 *
 	 * @param {Function|String} key The plugin constructor or {@link module:core/plugin~PluginInterface.pluginName name}.
 	 * @returns {module:core/plugin~PluginInterface}
@@ -130,7 +130,7 @@ export default class PluginCollection {
 			 * property.
 			 *
 			 * **Note**: You can use `{@link module:core/plugincollection~PluginCollection#has editor.plugins.has()}`
-			 * to check if plugin was loaded.
+			 * to check if a plugin was loaded.
 			 *
 			 * @error plugincollection-plugin-not-loaded
 			 * @param {String} plugin The name of the plugin which is not loaded.
@@ -165,7 +165,7 @@ export default class PluginCollection {
 	 * @param {Array.<Function|String>} plugins An array of {@link module:core/plugin~PluginInterface plugin constructors}
 	 * or {@link module:core/plugin~PluginInterface.pluginName plugin names}. The second option (names) works only if
 	 * `availablePlugins` were passed to the {@link #constructor}.
-	 * @param {Array.<String|Function>} [removePlugins] Names of plugins or plugin constructors
+	 * @param {Array.<String|Function>} [removePlugins] Names of the plugins or plugin constructors
 	 * that should not be loaded (despite being specified in the `plugins` array).
 	 * @returns {Promise.<module:core/plugin~LoadedPlugins>} A promise which gets resolved once all plugins are loaded
 	 * and available in the collection.
@@ -196,7 +196,7 @@ export default class PluginCollection {
 			 * **If you see this warning when using one of the editor creators directly** (not a build), then it means
 			 * that you tried loading plugins by name. However, unlike CKEditor 4, CKEditor 5 does not implement a "plugin loader".
 			 * This means that CKEditor 5 does not know where to load the plugin modules from. Therefore, you need to
-			 * provide each plugin through reference (as a constructor function). Check out the examples in
+			 * provide each plugin through a reference (as a constructor function). Check out the examples in
 			 * {@glink builds/guides/integration/advanced-setup#scenario-2-building-from-source "Building from source"}.
 			 *
 			 * @error plugincollection-plugin-not-found
@@ -204,7 +204,7 @@ export default class PluginCollection {
 			 */
 			const errorId = 'plugincollection-plugin-not-found';
 
-			// Log the error, so it's more visible on the console. Hopefully, for better DX.
+			// Log the error, so it's more visible on the console. Hopefully, for a better DX.
 			logError( errorId, { plugins: missingPlugins } );
 
 			return Promise.reject( new CKEditorError( errorId, context, { plugins: missingPlugins } ) );
@@ -230,10 +230,10 @@ export default class PluginCollection {
 					/**
 					 * It was not possible to load the plugin.
 					 *
-					 * This is a generic error logged to the console when a JavaSript error is thrown during the initialization
+					 * This is a generic error logged to the console when a JavaScript error is thrown during the initialization
 					 * of one of the plugins.
 					 *
-					 * If you correctly handled the promise returned by the editor's `create()` method (like shown below),
+					 * If you correctly handled the promise returned by the editor's `create()` method (as shown below),
 					 * you will find the original error logged to the console, too:
 					 *
 					 *		ClassicEditor.create( document.getElementById( 'editor' ) )
@@ -398,11 +398,11 @@ export default class PluginCollection {
 			 * The second option is that your `node_modules/` directory contains duplicated versions of the same
 			 * CKEditor 5 packages. Normally, on clean installations, npm deduplicates packages in `node_modules/`, so
 			 * it may be enough to call `rm -rf node_modules && npm i`. However, if you installed conflicting versions
-			 * of packages, their dependencies may need to be installed in more than one version which may lead to this
+			 * of some packages, their dependencies may need to be installed in more than one version which may lead to this
 			 * warning.
 			 *
 			 * Technically speaking, this error occurs because after adding a plugin to an existing editor build
-			 * dependencies of this plugin are being duplicated.
+			 * the dependencies of this plugin are being duplicated.
 			 * They are already built into that editor build and now get added for the second time as dependencies
 			 * of the plugin you are installing.
 			 *

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

@@ -15,8 +15,8 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
- * Downcast dispatcher is a central point of downcasting (conversion from the model to the view), which is a process of reacting to changes
- * in the model and firing a set of events. Callbacks listening to these events are called converters. The
+ * The downcast dispatcher is a central point of downcasting (conversion from the model to the view), which is a process of reacting
+ * to changes in the model and firing a set of events. Callbacks listening to these events are called converters. The
  * converters' role is to convert the model changes to changes in view (for example, adding view nodes or
  * changing attributes on view elements).
  *
@@ -52,7 +52,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} &ndash; If a marker was added.
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} &ndash; If a marker was removed.
  *
- * Note that changing a marker is done through removing the marker from the old range and adding it on the new range,
+ * Note that changing a marker is done through removing the marker from the old range and adding it to the new range,
  * so both events are fired.
  *
  * Finally, downcast dispatcher also handles firing events for the {@link module:engine/model/selection model selection}
@@ -65,9 +65,9 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}
  * &ndash; Fired for every marker that contains a selection.
  *
- * Unlike model tree and markers, events for selection are not fired for changes but for selection state.
+ * Unlike the model tree and the markers, the events for selection are not fired for changes but for a selection state.
  *
- * When providing custom listeners for downcast dispatcher, remember to check whether a given change has not been
+ * When providing custom listeners for a downcast dispatcher, remember to check whether a given change has not been
  * {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} yet.
  *
  * When providing custom listeners for downcast dispatcher, keep in mind that any callback that has
@@ -125,7 +125,7 @@ export default class DowncastDispatcher {
 		this.conversionApi = Object.assign( { dispatcher: this }, conversionApi );
 
 		/**
-		 * Maps conversion event names that will trigger element reconversion for given element name.
+		 * Maps conversion event names that will trigger element reconversion for a given element name.
 		 *
 		 * @type {Map<String, String>}
 		 * @private
@@ -217,7 +217,7 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts conversion of attribute change on given `range`.
+	 * Starts a conversion of an attribute change on a given `range`.
 	 *
 	 * For each node in the given `range`, {@link #event:attribute attribute event} is fired with the passed data.
 	 *
@@ -760,7 +760,7 @@ export default class DowncastDispatcher {
 	 */
 
 	/**
-	 * Fired when a new marker is added to the model. Also fired when collapsed model selection that is inside a marker is converted.
+	 * Fired when a new marker is added to the model. Also fired when a collapsed model selection that is inside a marker is converted.
 	 *
 	 * `addMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
 	 * `addMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
@@ -770,17 +770,17 @@ export default class DowncastDispatcher {
 	 * If the marker range is not collapsed:
 	 *
 	 * * the event is fired for each item in the marker range one by one,
-	 * * `conversionApi.consumable` includes each item of the marker range and the consumable value is same as event name.
+	 * * `conversionApi.consumable` includes each item of the marker range and the consumable value is same as the event name.
 	 *
 	 * If the marker range is collapsed:
 	 *
 	 * * there is only one event,
-	 * * `conversionApi.consumable` includes marker range with event name.
+	 * * `conversionApi.consumable` includes marker range with the event name.
 	 *
-	 * If selection inside a marker is converted:
+	 * If the selection inside a marker is converted:
 	 *
 	 * * there is only one event,
-	 * * `conversionApi.consumable` includes selection instance with event name.
+	 * * `conversionApi.consumable` includes the selection instance with the event name.
 	 *
 	 * @event addMarker
 	 * @param {Object} data Additional information about the change.
@@ -795,7 +795,7 @@ export default class DowncastDispatcher {
 	 */
 
 	/**
-	 * Fired when marker is removed from the model.
+	 * Fired when a marker is removed from the model.
 	 *
 	 * `removeMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
 	 * `removeMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
@@ -879,8 +879,8 @@ function elementOrTextProxyToView( item, mapper ) {
  */
 
 /**
- * Stores information about what parts of processed model item are still waiting to be handled. After a piece of model item
- * was converted, appropriate consumable value should be {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}.
+ * Stores the information about what parts of a processed model item are still waiting to be handled. After a piece of a model item was
+ * converted, an appropriate consumable value should be {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}.
  *
  * @member {module:engine/conversion/modelconsumable~ModelConsumable} #consumable
  */
@@ -898,13 +898,13 @@ function elementOrTextProxyToView( item, mapper ) {
  */
 
 /**
- * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate data during conversion.
+ * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate the data during conversion.
  *
  * @member {module:engine/view/downcastwriter~DowncastWriter} #writer
  */
 
 /**
- * An object with an additional configuration which can be used during conversion process. Available only for data downcast conversion.
+ * An object with an additional configuration which can be used during the conversion process. Available only for data downcast conversion.
  *
  * @member {Object} #options
  */

+ 7 - 7
packages/ckeditor5-list/src/liststyleediting.js

@@ -114,9 +114,9 @@ export default class ListStyleEditing extends Plugin {
 		const editor = this.editor;
 		const model = editor.model;
 
-		// First the most-outer `listItem` in the first list reference.
-		// If found, lists should be merged and this `listItem` provides the `listStyle` attribute
-		// and it' also a starting point when searching for items in the second list.
+		// First the outer-most`listItem` in the first list reference.
+		// If found, the lists should be merged and this `listItem` provides the `listStyle` attribute
+		// and it is also a starting point when searching for items in the second list.
 		let firstMostOuterItem;
 
 		// Check whether the removed content is between two lists.
@@ -249,8 +249,8 @@ function downcastListStyleAttribute() {
 
 	// Checks whether specified list items belong to the same list.
 	//
-	// @param {module:engine/model/element~Element} listItem1 The first list item to check.
-	// @param {module:engine/model/element~Element|null} listItem2 The second list item to check.
+	// @param {module:engine/model/element~Element} `listItem1` The first list item to check.
+	// @param {module:engine/model/element~Element|null} `listItem2` The second list item to check.
 	// @returns {Boolean}
 	function areRepresentingSameList( listItem1, listItem2 ) {
 		return listItem2 &&
@@ -295,7 +295,7 @@ function fixListAfterIndentListCommand( editor ) {
 
 		const itemsToUpdate = changedItems.filter( item => item.getAttribute( 'listIndent' ) === rootIndent );
 
-		// A case where a few list items are intended must be checked separately
+		// A case where a few list items are indented must be checked separately
 		// since `getSiblingListItem()` returns the first changed element.
 		// ■ List item 1.
 		//     ○ [List item 2.
@@ -570,7 +570,7 @@ function restoreDefaultListStyle( editor ) {
 	};
 }
 
-// Returns `listItem` that were inserted or changed.
+// Returns the `listItem` that was inserted or changed.
 //
 // @param {Array.<Object>} changes The changes list returned by the differ.
 // @returns {Array.<module:engine/model/element~Element>}

+ 7 - 7
packages/ckeditor5-media-embed/src/ui/mediaformview.js

@@ -43,7 +43,7 @@ export default class MediaFormView extends View {
 		const t = locale.t;
 
 		/**
-		 * Tracks information about DOM focus in the form.
+		 * Tracks information about the DOM focus in the form.
 		 *
 		 * @readonly
 		 * @member {module:utils/focustracker~FocusTracker}
@@ -110,10 +110,10 @@ export default class MediaFormView extends View {
 			focusTracker: this.focusTracker,
 			keystrokeHandler: this.keystrokes,
 			actions: {
-				// Navigate form fields backwards using the Shift + Tab keystroke.
+				// Navigate form fields backwards using the <kbd>Shift</kbd> + <kbd>Tab</kbd> keystroke.
 				focusPrevious: 'shift + tab',
 
-				// Navigate form fields forwards using the Tab key.
+				// Navigate form fields forwards using the <kbd>Tab</kbd> key.
 				focusNext: 'tab'
 			}
 		} );
@@ -200,9 +200,9 @@ export default class MediaFormView extends View {
 		this.keystrokes.set( 'arrowup', stopPropagation );
 		this.keystrokes.set( 'arrowdown', stopPropagation );
 
-		// Intercept the "selectstart" event, which is blocked by default because of the default behavior
+		// Intercept the `selectstart` event, which is blocked by default because of the default behavior
 		// of the DropdownView#panelView.
-		// TODO: blocking "selectstart" in the #panelView should be configurable per–drop–down instance.
+		// TODO: blocking `selectstart` in the #panelView should be configurable per–drop–down instance.
 		this.listenTo( this.urlInputView.element, 'selectstart', ( evt, domEvt ) => {
 			domEvt.stopPropagation();
 		}, { priority: 'high' } );
@@ -285,7 +285,7 @@ export default class MediaFormView extends View {
 		inputField.placeholder = 'https://example.com';
 
 		inputField.on( 'input', () => {
-			// Display the tip text only when there's some value. Otherwise fall back to the default info text.
+			// Display the tip text only when there is some value. Otherwise fall back to the default info text.
 			labeledInput.infoText = inputField.element.value ? this._urlInputViewInfoTip : this._urlInputViewInfoDefault;
 			this.mediaURLInputValue = inputField.element.value.trim();
 		} );
@@ -334,7 +334,7 @@ export default class MediaFormView extends View {
  */
 
 /**
- * Fired when the form view is canceled, e.g. click on {@link #cancelButtonView}.
+ * Fired when the form view is canceled, e.g. by a click on {@link #cancelButtonView}.
  *
  * @event cancel
  */

+ 12 - 11
packages/ckeditor5-table/src/converters/upcasttable.js

@@ -10,7 +10,7 @@
 import { createEmptyTableCell } from '../utils/common';
 
 /**
- * View table element to model table element conversion helper.
+ * View the table element to model the table element conversion helper.
  *
  * This conversion helper converts the table element as well as table rows.
  *
@@ -64,13 +64,14 @@ export default function upcastTable() {
 }
 
 /**
- * Conversion helper that skips empty <tr> from upcasting at the beginning of the table.
+ * A conversion helper that skips empty <tr> from upcasting at the beginning of the table.
  *
- * Empty row is considered a table model error but when handling clipboard data there could be rows that contain only row-spanned cells
+ * AN empty row is considered a table model error but when handling clipboard data there could be rows that contain only row-spanned cells
  * and empty TR-s are used to maintain table structure (also {@link module:table/tablewalker~TableWalker} assumes that there are only rows
- * that have related tableRow elements).
+ * that have related `tableRow` elements).
  *
- * *Note:* Only first empty rows are removed because those have no meaning and solves issue of improper table with all empty rows.
+ * *Note:* Only the first empty rows are removed because those have no meaning and it solves the issue
+ * of an improper table with all empty rows.
  *
  * @returns {Function} Conversion helper.
  */
@@ -109,24 +110,24 @@ function scanTable( viewTable ) {
 	//			<tbody><tr><td>3</td></tr></tbody>
 	//		</table>
 	//
-	// But browsers will render rows in order as: 1 as heading and 2 and 3 as the body.
+	// But browsers will render rows in order as: 1 as the heading and 2 and 3 as the body.
 	const headRows = [];
 	const bodyRows = [];
 
 	// Currently the editor does not support more then one <thead> section.
-	// Only the first <thead> from the view will be used as heading rows and others will be converted to body rows.
+	// Only the first <thead> from the view will be used as a heading row and the others will be converted to body rows.
 	let firstTheadElement;
 
 	for ( const tableChild of Array.from( viewTable.getChildren() ) ) {
-		// Only <thead>, <tbody> & <tfoot> from allowed table children can have <tr>s.
-		// The else is for future purposes (mainly <caption>).
+		// Only `<thead>`, `<tbody>` & `<tfoot>` from allowed table children can have `<tr>`s.
+		// The else is for future purposes (mainly `<caption>`).
 		if ( tableChild.name === 'tbody' || tableChild.name === 'thead' || tableChild.name === 'tfoot' ) {
-			// Save the first <thead> in the table as table header - all other ones will be converted to table body rows.
+			// Save the first `<thead>` in the table as table header - all other ones will be converted to table body rows.
 			if ( tableChild.name === 'thead' && !firstTheadElement ) {
 				firstTheadElement = tableChild;
 			}
 
-			// There might be some extra empty text nodes between the `tr`s.
+			// There might be some extra empty text nodes between the `<tr>`s.
 			// Make sure further code operates on `tr`s only. (#145)
 			const trs = Array.from( tableChild.getChildren() ).filter( el => el.is( 'element', 'tr' ) );
 

+ 4 - 4
packages/ckeditor5-table/src/tableediting.js

@@ -81,10 +81,10 @@ export default class TableEditing extends Plugin {
 			isSelectable: true
 		} );
 
-		// Allow all $block content inside table cell.
+		// Allow all $block content inside a table cell.
 		schema.extend( '$block', { allowIn: 'tableCell' } );
 
-		// Disallow table in table.
+		// Disallow a table in a table.
 		schema.addChildCheck( ( context, childDefinition ) => {
 			if ( childDefinition.name == 'table' && Array.from( context.getNames() ).includes( 'table' ) ) {
 				return false;
@@ -110,7 +110,7 @@ export default class TableEditing extends Plugin {
 
 		conversion.for( 'editingDowncast' ).add( downcastInsertCell() );
 
-		// Duplicates code - needed to properly refresh paragraph inside table cell.
+		// Duplicates code - needed to properly refresh paragraph inside a table cell.
 		editor.conversion.for( 'editingDowncast' ).elementToElement( {
 			model: 'paragraph',
 			view: convertParagraphInTableCell,
@@ -121,7 +121,7 @@ export default class TableEditing extends Plugin {
 		conversion.attributeToAttribute( { model: 'colspan', view: 'colspan' } );
 		conversion.attributeToAttribute( { model: 'rowspan', view: 'rowspan' } );
 
-		// Table heading columns conversion (change of heading rows requires reconversion of the whole table).
+		// Table heading columns conversion (a change of heading rows requires a reconversion of the whole table).
 		conversion.for( 'editingDowncast' ).add( downcastTableHeadingColumnsChange() );
 
 		// Define all the commands.