8
0
Anna Tomanek 8 лет назад
Родитель
Сommit
32a1e8fcc9

+ 1 - 1
packages/ckeditor5-list/README.md

@@ -8,7 +8,7 @@ CKEditor 5 lists feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-list/status.svg)](https://david-dm.org/ckeditor/ckeditor5-list)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-list/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-list?type=dev)
 
-Introduces ordered and unordered lists feature to CKEditor 5. More information about the project can be found at the following URL: <https://github.com/ckeditor/ckeditor5-list>.
+Introduces ordered (numbered) and unordered (bulleted) lists feature to CKEditor 5. More information about the project can be found at the following URL: <https://github.com/ckeditor/ckeditor5-list>.
 
 ## License
 

+ 45 - 45
packages/ckeditor5-list/src/converters.js

@@ -21,13 +21,13 @@ import ViewTreeWalker from '@ckeditor/ckeditor5-engine/src/view/treewalker';
 import viewWriter from '@ckeditor/ckeditor5-engine/src/view/writer';
 
 /**
- * Model to view converter for `listItem` model element insertion.
+ * A model-to-view converter for `listItem` model element insertion.
  *
- * It creates `<ul><li></li><ul>` (or `<ol>`) view structure out of `listItem` model element, inserts it at correct
- * position, and merges the list with surrounding lists (if able).
+ * It creates a `<ul><li></li><ul>` (or `<ol>`) view structure out of a `listItem` model element, inserts it at the correct
+ * position, and merges the list with surrounding lists (if available).
  *
  * @see module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:insert
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
  * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
  * @param {Object} conversionApi Conversion interface.
@@ -54,13 +54,13 @@ export function modelViewInsertion( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * Model to view converter for `type` attribute change on `listItem` model element.
+ * A model-to-view converter for `type` attribute change on `listItem` model element.
  *
- * This change means that `<li>`s parent changes from `<ul>` to `<ol>` (or vice versa). This is accomplished by breaking
- * view elements, changing their name and merging them.
+ * This change means that `<li>` elements parent changes from `<ul>` to `<ol>` (or vice versa). This is accomplished
+ * by breaking view elements, changing their name and merging them.
  *
  * @see module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:changeAttribute
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
  * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
  * @param {Object} conversionApi Conversion interface.
@@ -89,10 +89,10 @@ export function modelViewChangeType( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * Model to view converter for `listItem` model element remove.
+ * A model-to-view converter for `listItem` model element removal.
  *
  * @see module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:remove
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
  * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
  * @param {Object} conversionApi Conversion interface.
@@ -131,10 +131,10 @@ export function modelViewRemove( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * Model to view converter for `indent` attribute change on `listItem` model element.
+ * A model-to-view converter for `indent` attribute change on `listItem` model element.
  *
  * @see module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:changeAttribute
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
  * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
  * @param {Object} conversionApi Conversion interface.
@@ -176,8 +176,8 @@ export function modelViewChangeIndent( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * A special model to view converter introduced by {@link module:list/list~List List feature}. This converter is fired for
- * insert change of every model item, and should be fired before actual converter. The converter checks whether inserted
+ * A special model-to-view converter introduced by the {@link module:list/list~List list feature}. This converter is fired for
+ * insert change of every model item, and should be fired before the actual converter. The converter checks whether the inserted
  * model item is a non-`listItem` element. If it is, and it is inserted inside a view list, the converter breaks the
  * list so the model element is inserted to the view parent element corresponding to its model parent element.
  *
@@ -195,7 +195,7 @@ export function modelViewChangeIndent( evt, data, consumable, conversionApi ) {
  *		<listItem>bar</listItem>         <ul><li>foo</li><p>xxx</p><li>bar</li></ul>
  *
  * @see module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:insert
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
  * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
  * @param {Object} conversionApi Conversion interface.
@@ -299,7 +299,7 @@ export function modelViewSplitOnInsert( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * A special model to view converter introduced by {@link module:list/list~List List feature}. This converter takes care of
+ * A special model-to-view converter introduced by the {@link module:list/list~List list feature}. This converter takes care of
  * merging view lists after something is removed or moved from near them.
  *
  * Example:
@@ -316,7 +316,7 @@ export function modelViewSplitOnInsert( evt, data, consumable, conversionApi ) {
  *		                                 </ul>
  *
  * @see module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:remove
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
  * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume.
  * @param {Object} conversionApi Conversion interface.
@@ -335,17 +335,17 @@ export function modelViewMergeAfter( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * View to model converter that converts view `<li>` elements into `listItem` model elements.
+ * A view-to-model converter that converts `<li>` view elements into `listItem` model elements.
  *
- * To set correct values of `type` and `indent` attribute the converter:
+ * To set correct values of the `type` and `indent` attributes the converter:
  * * checks `<li>`'s parent,
- * * passes `data.indent` value when `<li>`'s sub-items are converted.
+ * * passes the `data.indent` value when `<li>`'s sub-items are converted.
  *
  * @see module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
- * @param {Object} data Object containing conversion input and a placeholder for conversion output and possibly other values.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
+ * @param {Object} data An object containing conversion input and a placeholder for conversion output and possibly other values.
  * @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable Values to consume.
- * @param {Object} conversionApi Conversion interface to be used by callback.
+ * @param {Object} conversionApi Conversion interface to be used by the callback.
  */
 export function viewModelConverter( evt, data, consumable, conversionApi ) {
 	if ( consumable.consume( data.input, { name: true } ) ) {
@@ -395,13 +395,13 @@ export function viewModelConverter( evt, data, consumable, conversionApi ) {
 }
 
 /**
- * View to model converter for `<ul>` and `<ol>` view elements, that cleans the input view out of garbage.
- * This is mostly to clean white spaces from between `<li>` view elements inside the view list element, however also
+ * A view-to-model converter for `<ul>` and `<ol>` view elements that cleans the input view of garbage.
+ * This is mostly to clean whitespaces from between `<li>` view elements inside the view list element, however, also
  * incorrect data can be cleared if the view was incorrect.
  *
  * @see module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
- * @param {Object} data Object containing conversion input and a placeholder for conversion output and possibly other values.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
+ * @param {Object} data An object containing conversion input and a placeholder for conversion output and possibly other values.
  * @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable Values to consume.
  */
 export function cleanList( evt, data, consumable ) {
@@ -418,11 +418,11 @@ export function cleanList( evt, data, consumable ) {
 }
 
 /**
- * View to model converter for `<li>`, that cleans white space formatting from the input view.
+ * A view-to-model converter for `<li>` elements that cleans whitespace formatting from the input view.
  *
  * @see module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
- * @param {Object} data Object containing conversion input and a placeholder for conversion output and possibly other values.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
+ * @param {Object} data An object containing conversion input and a placeholder for conversion output and possibly other values.
  * @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable Values to consume.
  */
 export function cleanListItem( evt, data, consumable ) {
@@ -462,13 +462,13 @@ export function cleanListItem( evt, data, consumable ) {
 }
 
 /**
- * Callback for model position to view position mapping for {@link module:engine/conversion/mapper~Mapper}. The callback fixes positions
- * between `listItem` elements, that would be incorrectly mapped because of how list items are represented in model
+ * The callback for model position to view position mapping for {@link module:engine/conversion/mapper~Mapper}. The callback fixes
+ * positions between `listItem` elements that would be incorrectly mapped because of how list items are represented in model
  * and view.
  *
  * @see module:engine/conversion/mapper~Mapper#event:modelToViewPosition
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
- * @param {Object} data Object containing additional data and placeholder for mapping result.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
+ * @param {Object} data An object containing additional data and placeholder for mapping result.
  */
 export function modelToViewPosition( evt, data ) {
 	const modelItem = data.modelPosition.nodeBefore;
@@ -495,13 +495,13 @@ export function modelToViewPosition( evt, data ) {
 }
 
 /**
- * Callback for view position to model position mapping for {@link module:engine/conversion/mapper~Mapper}. The callback fixes positions
- * between `<li>` elements, that would be incorrectly mapped because of how list items are represented in model
+ * The callback for view position to model position mapping for {@link module:engine/conversion/mapper~Mapper}. The callback fixes
+ * positions between `<li>` elements that would be incorrectly mapped because of how list items are represented in model
  * and view.
  *
  * @see module:engine/conversion/mapper~Mapper#event:viewToModelPosition
- * @param {module:utils/eventinfo~EventInfo} evt Object containing information about the fired event.
- * @param {Object} data Object containing additional data and placeholder for mapping result.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
+ * @param {Object} data An object containing additional data and placeholder for mapping result.
  */
 export function viewToModelPosition( evt, data ) {
 	const viewPos = data.viewPosition;
@@ -552,7 +552,7 @@ export function viewToModelPosition( evt, data ) {
 }
 
 /**
- * Post fixer that reacts to changes on document and fixed incorrect model states.
+ * Post-fixer that reacts to changes on document and fixes incorrect model states.
  *
  * Example:
  *
@@ -563,10 +563,10 @@ export function viewToModelPosition( evt, data ) {
  * Should become:
  *
  *		<listItem type="bulleted" indent=0>Item 1</listItem>
- *		<listItem type="bulleted" indent=1>Item 3</listItem>   <--- note that indent got postfixed.
+ *		<listItem type="bulleted" indent=1>Item 3</listItem>   <--- note that indent got post-fixed.
  *
- * @param {module:engine/model/document~Document} document Document to observe.
- * @returns {Function} Callback to be attached to {@link module:engine/model/document~Document#event:change document change event}.
+ * @param {module:engine/model/document~Document} document The document to observe.
+ * @returns {Function} A callback to be attached to the {@link module:engine/model/document~Document#event:change document change event}.
  */
 export function modelChangePostFixer( document ) {
 	return ( evt, type, changes, batch ) => {
@@ -700,9 +700,9 @@ function _fixItemsType( changePosition, fixPrevious, document, batch ) {
 }
 
 /**
- * Fixer for pasted content that includes list items.
+ * A fixer for pasted content that includes list items.
  *
- * Fixes indent of pasted list items so the pasted items match correctly to the context they are pasted into.
+ * It fixes indentation of pasted list items so the pasted items match correctly to the context they are pasted into.
  *
  * Example:
  *
@@ -719,7 +719,7 @@ function _fixItemsType( changePosition, fixPrevious, document, batch ) {
  *		<listItem type="bulleted" indent=2>Y/listItem>
  *		<listItem type="bulleted" indent=2>C</listItem>
  *
- * @param {module:utils/eventinfo~EventInfo} evt Event info object.
+ * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Array} args Arguments of {@link module:engine/controller/datacontroller~DataController#insertContent}.
  */
 export function modelIndentPasteFixer( evt, [ content, selection ] ) {

+ 4 - 4
packages/ckeditor5-list/src/indentcommand.js

@@ -19,15 +19,15 @@ export default class IndentCommand extends Command {
 	/**
 	 * Creates an instance of the command.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor instance.
-	 * @param {'forward'|'backward'} indentDirection Direction of indent. If it is equal to `backward`, the command
+	 * @param {module:core/editor/editor~Editor} editor The editor instance.
+	 * @param {'forward'|'backward'} indentDirection The direction of indent. If it is equal to `backward`, the command
 	 * will outdent a list item.
 	 */
 	constructor( editor, indentDirection ) {
 		super( editor );
 
 		/**
-		 * By how much the command will change list item's indent attribute.
+		 * Determines by how much the command will change the list item's indent attribute.
 		 *
 		 * @readonly
 		 * @private
@@ -44,7 +44,7 @@ export default class IndentCommand extends Command {
 	}
 
 	/**
-	 * Indents or outdents (depends on {@link #constructor}'s `indentDirection` parameter) selected list items.
+	 * Indents or outdents (depends on the {@link #constructor}'s `indentDirection` parameter) selected list items.
 	 *
 	 * @fires execute
 	 */

+ 10 - 10
packages/ckeditor5-list/src/list.js

@@ -17,8 +17,8 @@ import { parseKeystroke } from '@ckeditor/ckeditor5-utils/src/keyboard';
 import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
 
 /**
- * The lists feature. It introduces the `numberedList` and `bulletedList` buttons which
- * allows to convert paragraphs to/from list items and indent/outdent them.
+ * The list feature. It introduces the `numberedList` and `bulletedList` buttons that
+ * allow to convert paragraphs to and from list items and indent or outdent them.
  *
  * See also {@link module:list/listengine~ListEngine}.
  *
@@ -48,8 +48,8 @@ export default class List extends Plugin {
 		this._addButton( 'numberedList', t( 'Numbered List' ), numberedListIcon );
 		this._addButton( 'bulletedList', t( 'Bulleted List' ), bulletedListIcon );
 
-		// Overwrite default enter key behavior.
-		// If enter key is pressed with selection collapsed in empty list item, outdent it instead of breaking it.
+		// Overwrite default Enter key behavior.
+		// If Enter key is pressed with selection collapsed in empty list item, outdent it instead of breaking it.
 		this.listenTo( this.editor.editing.view, 'enter', ( evt, data ) => {
 			const doc = this.editor.document;
 			const positionParent = doc.selection.getLastPosition().parent;
@@ -62,9 +62,9 @@ export default class List extends Plugin {
 			}
 		} );
 
-		// Add tab key support.
-		// When in list item, pressing tab should indent list item, if possible.
-		// Pressing Shift+Tab shout outdent list item.
+		// Add Tab key support.
+		// When in list item, pressing Tab should indent list item, if possible.
+		// Pressing Shift+Tab should outdent list item.
 		this.listenTo( this.editor.editing.view, 'keydown', ( evt, data ) => {
 			let commandName;
 
@@ -91,9 +91,9 @@ export default class List extends Plugin {
 	 * Helper method for initializing a button and linking it with an appropriate command.
 	 *
 	 * @private
-	 * @param {String} commandName Name of the command.
-	 * @param {Object} label Button label.
-	 * @param {String} icon Source of the icon.
+	 * @param {String} commandName The name of the command.
+	 * @param {Object} label The button label.
+	 * @param {String} icon The source of the icon.
 	 */
 	_addButton( commandName, label, icon ) {
 		const editor = this.editor;

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

@@ -20,14 +20,14 @@ export default class ListCommand extends Command {
 	/**
 	 * Creates an instance of the command.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor instance.
+	 * @param {module:core/editor/editor~Editor} editor The editor instance.
 	 * @param {'numbered'|'bulleted'} type List type that will be handled by this command.
 	 */
 	constructor( editor, type ) {
 		super( editor );
 
 		/**
-		 * The type of list created by the command.
+		 * The type of the list created by the command.
 		 *
 		 * @readonly
 		 * @member {'numbered'|'bulleted'}
@@ -35,7 +35,7 @@ export default class ListCommand extends Command {
 		this.type = type == 'bulleted' ? 'bulleted' : 'numbered';
 
 		/**
-		 * Flag indicating whether the command is active, which means that selection starts in a list of the same type.
+		 * A flag indicating whether the command is active, which means that the selection starts in a list of the same type.
 		 *
 		 * @observable
 		 * @readonly
@@ -52,12 +52,12 @@ export default class ListCommand extends Command {
 	}
 
 	/**
-	 * Executes command.
+	 * Executes the command.
 	 *
 	 * @protected
-	 * @param {Object} [options] Options for executed command.
-	 * @param {module:engine/model/batch~Batch} [options.batch] Batch to collect all the change steps.
-	 * New batch will be created if this option is not set.
+	 * @param {Object} [options] Options for the executed command.
+	 * @param {module:engine/model/batch~Batch} [options.batch] A batch to collect all the change steps.
+	 * A new batch will be created if this option is not set.
 	 */
 	execute( options = {} ) {
 		const document = this.editor.document;

+ 1 - 1
packages/ckeditor5-list/src/listengine.js

@@ -30,7 +30,7 @@ import {
 } from './converters';
 
 /**
- * The engine of the lists feature. It handles creating, editing and removing lists and list items.
+ * The engine of the list feature. It handles creating, editing and removing lists and list items.
  * It registers the `numberedList`, `bulletedList`, `indentList` and `outdentList` commands.
  *
  * @extends module:core/plugin~Plugin

+ 5 - 5
packages/ckeditor5-list/src/viewlistitemelement.js

@@ -10,7 +10,7 @@
 import ViewContainerElement from '@ckeditor/ckeditor5-engine/src/view/containerelement';
 
 /**
- * View element class representing list item (`<li>`). It extends {@link module:engine/view/containerelement~ContainerElement}
+ * View element class representing a list item (`<li>`). It extends {@link module:engine/view/containerelement~ContainerElement}
  * and overwrites {@link module:list/viewlistitemelement~ViewListItemElement#getFillerOffset evaluating whether filler offset}
  * is needed.
  *
@@ -18,11 +18,11 @@ import ViewContainerElement from '@ckeditor/ckeditor5-engine/src/view/containere
  */
 export default class ViewListItemElement extends ViewContainerElement {
 	/**
-	 * Creates `<li>` view item.
+	 * Creates a `<li>` view item.
 	 *
-	 * @param {Object|Iterable} [attrs] Collection of attributes.
-	 * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children] List of nodes to be inserted
-	 * into created element.
+	 * @param {Object|Iterable} [attrs] A collection of attributes.
+	 * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children] The list of nodes to be inserted
+	 * into the created element.
 	 */
 	constructor( attrs, children ) {
 		super( 'li', attrs, children );