Przeglądaj źródła

Docs: To-do list API docs corrected.

Anna Tomanek 6 lat temu
rodzic
commit
bbde111ddf

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

@@ -95,8 +95,8 @@ export function modelViewRemove( model ) {
  * A model-to-view converter for the `type` attribute change on the `listItem` model element.
  *
  * This change means that the `<li>` element parent changes from `<ul>` to `<ol>` (or vice versa). This is accomplished
- * by breaking view elements and changing their name. Next {@link module:list/converters~modelViewMergeAfterChangeType}
- * converter will try to merge split nodes.
+ * by breaking view elements and changing their name. The next {@link module:list/converters~modelViewMergeAfterChangeType}
+ * converter will attempt to merge split nodes.
  *
  * Splitting this conversion into 2 steps makes it possible to add an additional conversion in the middle.
  * Check {@link module:list/todolistconverters~modelViewChangeType} to see an example of it.
@@ -128,7 +128,7 @@ export function modelViewChangeType( evt, data, conversionApi ) {
 }
 
 /**
- * A model-to-view converter that try to merge nodes split by {@link module:list/converters~modelViewChangeType}.
+ * A model-to-view converter that attempts to merge nodes split by {@link module:list/converters~modelViewChangeType}.
  *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
  * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.

+ 2 - 2
packages/ckeditor5-list/src/todolist.js

@@ -15,8 +15,8 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 /**
  * The to-do list feature.
  *
- * This is a "glue" plugin which loads the {@link module:list/todolistediting~TodoListEditing to-do list editing feature}
- * and {@link module:list/todolistui~TodoListUI list UI feature}.
+ * This is a "glue" plugin that loads the {@link module:list/todolistediting~TodoListEditing to-do list editing feature}
+ * and the {@link module:list/todolistui~TodoListUI to-do list UI feature}.
  *
  * @extends module:core/plugin~Plugin
  */

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

@@ -22,7 +22,7 @@ export default class TodoListCheckCommand extends Command {
 		super( editor );
 
 		/**
-		 * Flag indicating whether the command is active. The command is active when at least one of
+		 * A flag indicating whether the command is active. The command is active when at least one of
 		 * {@link module:engine/model/selection~Selection selected} elements is a to-do list item.
 		 *
 		 * @observable
@@ -31,7 +31,7 @@ export default class TodoListCheckCommand extends Command {
 		 */
 
 		/**
-		 * A List of to-do list item selected by the {@link module:engine/model/selection~Selection}.
+		 * A list of to-do list items selected by the {@link module:engine/model/selection~Selection}.
 		 *
 		 * @observable
 		 * @readonly
@@ -39,7 +39,7 @@ export default class TodoListCheckCommand extends Command {
 		 */
 
 		/**
-		 * List of to-do list items selected by the {@link module:engine/model/selection~Selection}.
+		 * A list of to-do list items selected by the {@link module:engine/model/selection~Selection}.
 		 *
 		 * @protected
 		 * @type {Array.<module:engine/model/element~Element>}
@@ -54,7 +54,7 @@ export default class TodoListCheckCommand extends Command {
 	}
 
 	/**
-	 * Updates the command's {@link #value} and {@link #isEnabled} based on the current selection.
+	 * Updates the command's {@link #value} and {@link #isEnabled} properties based on the current selection.
 	 */
 	refresh() {
 		this._selectedElements = this._getSelectedItems();
@@ -94,7 +94,7 @@ export default class TodoListCheckCommand extends Command {
 	 *
 	 * @param {Object} [options]
 	 * @param {Boolean} [options.forceValue] If set, it will force the command behavior. If `true`, the command will apply
-	 * the attribute, otherwise the command will remove the attribute. If not set, the command will look for its current
+	 * the attribute. Otherwise, the command will remove the attribute. If not set, the command will look for its current
 	 * value to decide what it should do.
 	 */
 	execute( options = {} ) {

+ 16 - 16
packages/ckeditor5-list/src/todolistconverters.js

@@ -13,9 +13,9 @@ import { generateLiInUl, injectViewList, findInRange } from './utils';
 import createElement from '@ckeditor/ckeditor5-utils/src/dom/createelement';
 
 /**
- * A model-to-view converter for `listItem` model element insertion.
+ * A model-to-view converter for the `listItem` model element insertion.
  *
- * It converts `listItem` model element to an unordered list with {@link module:engine/view/uielement~UIElement checkbox element}
+ * It converts the `listItem` model element to an unordered list with a {@link module:engine/view/uielement~UIElement checkbox element}
  * at the beginning of each list item. It also merges the list with surrounding lists (if available).
  *
  * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
@@ -60,7 +60,7 @@ export function modelViewInsertion( model, onCheckboxChecked ) {
 }
 
 /**
- * A model-to-view converter for model `$text` element inside a to-do list item.
+ * A model-to-view converter for the model `$text` element inside a to-do list item.
  *
  * It takes care of creating text after the {@link module:engine/view/uielement~UIElement checkbox UI element}.
  *
@@ -95,7 +95,7 @@ export function modelViewTextInsertion( evt, data, conversionApi ) {
 }
 
 /**
- * A model-to-view converter for `listItem` model element insertion.
+ * A model-to-view converter for the `listItem` model element insertion.
  *
  * It is used by {@link module:engine/controller/datacontroller~DataController}.
  *
@@ -148,7 +148,7 @@ export function dataModelViewInsertion( model ) {
 }
 
 /**
- * A model-to-view converter for model `$text` element inside a to-do list item.
+ * A model-to-view converter for the model `$text` element inside a to-do list item.
  *
  * It is used by {@link module:engine/controller/datacontroller~DataController}.
  *
@@ -181,16 +181,16 @@ export function dataModelViewTextInsertion( evt, data, conversionApi ) {
 }
 
 /**
- * A view-to-model converter for checkbox element inside a view list item.
+ * A view-to-model converter for the checkbox element inside a view list item.
  *
- * It changes `listType` of model `listItem` to a `todo` value.
- * When view checkbox is marked as checked the additional `todoListChecked="true"` attribute is added to model item.
+ * It changes the `listType` of the model `listItem` to a `todo` value.
+ * When a view checkbox element is marked as checked, an additional `todoListChecked="true"` attribute is added to the model item.
  *
  * It is used by {@link module:engine/controller/datacontroller~DataController}.
  *
  * @see module:engine/conversion/upcastdispatcher~UpcastDispatcher#event:element
  * @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 {Object} data An object containing conversion input, a placeholder for conversion output and possibly other values.
  * @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion interface to be used by the callback.
  */
 export function dataViewModelCheckmarkInsertion( evt, data, conversionApi ) {
@@ -218,9 +218,9 @@ export function dataViewModelCheckmarkInsertion( evt, data, conversionApi ) {
 }
 
 /**
- * A model-to-view converter for `listType` attribute change on `listItem` model element.
+ * A model-to-view converter for the `listType` attribute change on the `listItem` model element.
  *
- * This change means that `<li>` elements parent changes to `<ul class="todo-list">` and
+ * This change means that the `<li>` element parent changes to `<ul class="todo-list">` and a
  * {@link module:engine/view/uielement~UIElement checkbox UI element} is added at the beginning
  * of the list item element (or vice versa).
  *
@@ -230,7 +230,7 @@ export function dataViewModelCheckmarkInsertion( evt, data, conversionApi ) {
  * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
  *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
- * @param {Function} onCheckedChange Callback fired after clicking on checkmark element.
+ * @param {Function} onCheckedChange Callback fired after clicking the checkbox UI element.
  * @returns {Function} Returns a conversion callback.
  */
 export function modelViewChangeType( onCheckedChange ) {
@@ -252,14 +252,14 @@ export function modelViewChangeType( onCheckedChange ) {
 }
 
 /**
- * A model-to-view converter for `todoListChecked` attribute change on `listItem` model element.
+ * A model-to-view converter for the `todoListChecked` attribute change on the `listItem` model element.
  *
- * It marks {@link module:engine/view/uielement~UIElement checkbox UI element} as checked.
+ * It marks the {@link module:engine/view/uielement~UIElement checkbox UI element} as checked.
  *
  * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
  *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
- * @param {Function} onCheckedChange Callback fired after clicking on checkmark element.
+ * @param {Function} onCheckedChange Callback fired after clicking the checkbox UI element.
  * @returns {Function} Returns a conversion callback.
  */
 export function modelViewChangeChecked( onCheckedChange ) {
@@ -286,7 +286,7 @@ export function modelViewChangeChecked( onCheckedChange ) {
 	};
 }
 
-// Creates checkbox UI element.
+// Creates a checkbox UI element.
 //
 // @private
 // @param {module:engine/model/item~Item} modelItem

+ 16 - 16
packages/ckeditor5-list/src/todolistediting.js

@@ -26,10 +26,10 @@ import {
 import { findInRange } from './utils';
 
 /**
- * The engine of the to-do list feature. It handles creating, editing and removing to-do lists and its items.
+ * The engine of the to-do list feature. It handles creating, editing and removing to-do lists and their items.
  *
- * It registers all functionalities of {@link module:list/listediting~ListEditing list editing plugin} and extends
- * it by `'todoList'` command.
+ * It registers the entire functionality of the {@link module:list/listediting~ListEditing list editing plugin} and extends
+ * it with the `'todoList'` command.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -88,7 +88,7 @@ export default class TodoListEditing extends Plugin {
 
 		data.upcastDispatcher.on( 'element:input', dataViewModelCheckmarkInsertion, { priority: 'high' } );
 
-		// Collect all view nodes that have changed and use it to check if checkmark UI element is going to
+		// Collect all view nodes that have changed and use it to check if the checkbox UI element is going to
 		// be re-rendered. If yes than view post-fixer should verify view structure.
 		const changedViewNodes = new Set();
 
@@ -99,7 +99,7 @@ export default class TodoListEditing extends Plugin {
 			viewRoot.on( 'change:children', ( evt, node ) => changedViewNodes.add( node ) );
 		}
 
-		// Move all uiElements after a checkmark element.
+		// Move all uiElements after a checkbox element.
 		viewDocument.registerPostFixer( writer => {
 			const changedCheckmarkElements = getChangedCheckmarkElements( writer, changedViewNodes );
 
@@ -108,7 +108,7 @@ export default class TodoListEditing extends Plugin {
 			return moveUIElementsAfterCheckmark( writer, changedCheckmarkElements );
 		} );
 
-		// Move selection after a checkmark element.
+		// Move selection after a checkbox element.
 		viewDocument.registerPostFixer( writer => moveSelectionAfterCheckmark( writer, viewDocument.selection ) );
 
 		// Jump at the end of the previous node on left arrow key press, when selection is after the checkbox.
@@ -161,11 +161,11 @@ export default class TodoListEditing extends Plugin {
 	}
 
 	/**
-	 * Handles checkmark element change, moves selection to the corresponding model item to makes it possible
-	 * to toggle `todoListChecked` attribute using command and restore the selection position.
+	 * Handles the checkbox element change, moves the selection to the corresponding model item to make it possible
+	 * to toggle the `todoListChecked` attribute using the command, and restores the selection position.
 	 *
-	 * Some say it's a hack :) Moving selection only for executing the command on a certain node and restoring it after,
-	 * it's not a clear solution. We need to design an API for using commands beyond the selection range.
+	 * Some say it's a hack :) Moving the selection only for executing the command on a certain node and restoring it after,
+	 * is not a clear solution. We need to design an API for using commands beyond the selection range.
 	 * See https://github.com/ckeditor/ckeditor5/issues/1954.
 	 *
 	 * @private
@@ -184,7 +184,7 @@ export default class TodoListEditing extends Plugin {
 	}
 }
 
-// Moves all uiElements in the to-do list item after the checkmark element.
+// Moves all UI elements in the to-do list item after the checkbox element.
 //
 // @private
 // @param {module:engine/view/downcastwriter~DowncastWriter} writer
@@ -215,7 +215,7 @@ function moveUIElementsAfterCheckmark( writer, uiElements ) {
 	return hasChanged;
 }
 
-// Moves selection in the to-do list item after the checkmark element.
+// Moves the selection in the to-do list item after the checkbox element.
 //
 // @private
 // @param {module:engine/view/downcastwriter~DowncastWriter} writer
@@ -249,8 +249,8 @@ function moveSelectionAfterCheckmark( writer, selection ) {
 	return false;
 }
 
-// Handles left arrow key and move selection at the end of the previous block element if the selection is just after
-// the checkmark element. In other words, it jumps over the checkmark element when moving the selection to the left.
+// Handles the left arrow key and moves the selection at the end of the previous block element if the selection is just after
+// the checkbox element. In other words, it jumps over the checkbox element when moving the selection to the left.
 //
 // @private
 // @param {Function} stopKeyEvent
@@ -276,7 +276,7 @@ function jumpOverCheckmarkOnLeftArrowKeyPress( stopKeyEvent, model ) {
 	}
 }
 
-// Gets list of all checkmark elements that are going to be rendered.
+// Gets the list of all checkbox elements that are going to be rendered.
 //
 // @private
 // @param {module:engine/view/view~View>} editingView
@@ -296,7 +296,7 @@ function getChangedCheckmarkElements( editingView, changedViewNodes ) {
 	return elements;
 }
 
-// Returns list item ancestor of given element.
+// Returns the list item ancestor of a given element.
 //
 // @private
 // @param {module:engine/view/item~Item} item

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

@@ -16,7 +16,7 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 
 /**
  * The to-do list UI feature. It introduces the `'todoList'` button that
- * allow to convert elements to and from list items and indent or outdent them.
+ * allows to convert elements to and from to-do list items and to indent or outdent them.
  *
  * @extends module:core/plugin~Plugin
  */

+ 34 - 34
packages/ckeditor5-list/src/utils.js

@@ -25,9 +25,9 @@ export function createViewListItemElement( writer ) {
 }
 
 /**
- * Helper function that creates a `<ul><li></li></ul>` or (`<ol>`) structure out of given `modelItem` model `listItem` element.
- * Then, it binds created view list item (<li>) with model `listItem` element.
- * The function then returns created view list item (<li>).
+ * Helper function that creates a `<ul><li></li></ul>` or (`<ol>`) structure out of the given `modelItem` model `listItem` element.
+ * Then, it binds the created view list item (<li>) with the model `listItem` element.
+ * The function then returns the created view list item (<li>).
  *
  * @param {module:engine/model/item~Item} modelItem Model list item.
  * @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion interface.
@@ -49,9 +49,9 @@ export function generateLiInUl( modelItem, conversionApi ) {
 }
 
 /**
- * Helper function that takes model list item element `modelItem`, corresponding view list item element `injectedItem`
- * that is not added to the view and is inside a view list element (`ul` or `ol`) and is that's list only child.
- * The list is inserted at correct position (element breaking may be needed) and then merged with it's siblings.
+ * Helper function that inserts a view list at a correct place and merges it with its siblings.
+ * It takes a model list item element (`modelItem`) and a corresponding view list item element (`injectedItem`). The view list item
+ * should be in a view list element (`<ul>` or `<ol>`) and should be its only child.
  * See comments below to better understand the algorithm.
  *
  * @param {module:engine/view/item~Item} modelItem Model list item.
@@ -64,12 +64,12 @@ export function injectViewList( modelItem, injectedItem, conversionApi, model )
 	const mapper = conversionApi.mapper;
 	const viewWriter = conversionApi.writer;
 
-	// Position where view list will be inserted.
+	// The position where the view list will be inserted.
 	let insertPosition = mapper.toViewPosition( model.createPositionBefore( modelItem ) );
 
-	// 1. Find previous list item that has same or smaller indent. Basically we are looking for a first model item
-	// that is "parent" or "sibling" of injected model item.
-	// If there is no such list item, it means that injected list item is the first item in "its list".
+	// 1. Find the previous list item that has the same or smaller indent. Basically we are looking for the first model item
+	// that is a "parent" or "sibling" of the injected model item.
+	// If there is no such list item, it means that the injected list item is the first item in "its list".
 	const refItem = getSiblingListItem( modelItem.previousSibling, {
 		sameIndent: true,
 		smallerIndent: true,
@@ -78,19 +78,19 @@ export function injectViewList( modelItem, injectedItem, conversionApi, model )
 	const prevItem = modelItem.previousSibling;
 
 	if ( refItem && refItem.getAttribute( 'listIndent' ) == modelItem.getAttribute( 'listIndent' ) ) {
-		// There is a list item with same indent - we found same-level sibling.
-		// Break the list after it. Inserted view item will be inserted in the broken space.
+		// There is a list item with the same indent - we found the same-level sibling.
+		// Break the list after it. The inserted view item will be added in the broken space.
 		const viewItem = mapper.toViewElement( refItem );
 		insertPosition = viewWriter.breakContainer( viewWriter.createPositionAfter( viewItem ) );
 	} else {
-		// There is no list item with same indent. Check previous model item.
+		// There is no list item with the same indent. Check the previous model item.
 		if ( prevItem && prevItem.name == 'listItem' ) {
-			// If it is a list item, it has to have lower indent.
-			// It means that inserted item should be added to it as its nested item.
+			// If it is a list item, it has to have a lower indent.
+			// It means that the inserted item should be added to it as its nested item.
 			insertPosition = mapper.toViewPosition( model.createPositionAt( prevItem, 'end' ) );
 		} else {
-			// Previous item is not a list item (or does not exist at all).
-			// Just map the position and insert the view item at mapped position.
+			// The previous item is not a list item (or does not exist at all).
+			// Just map the position and insert the view item at the mapped position.
 			insertPosition = mapper.toViewPosition( model.createPositionBefore( modelItem ) );
 		}
 	}
@@ -100,7 +100,7 @@ export function injectViewList( modelItem, injectedItem, conversionApi, model )
 	// Insert the view item.
 	viewWriter.insert( insertPosition, injectedList );
 
-	// 2. Handle possible children of injected model item.
+	// 2. Handle possible children of the injected model item.
 	if ( prevItem && prevItem.name == 'listItem' ) {
 		const prevView = mapper.toViewElement( prevItem );
 
@@ -142,19 +142,19 @@ export function injectViewList( modelItem, injectedItem, conversionApi, model )
 		}
 	}
 
-	// Merge inserted view list with its possible neighbour lists.
+	// Merge the inserted view list with its possible neighbor lists.
 	mergeViewLists( viewWriter, injectedList, injectedList.nextSibling );
 	mergeViewLists( viewWriter, injectedList.previousSibling, injectedList );
 }
 
 /**
- * Helper function that takes two parameters, that are expected to be view list elements, and merges them.
- * The merge happen only if both parameters are list elements of the same types (the same element name and the same class attributes).
+ * Helper function that takes two parameters that are expected to be view list elements, and merges them.
+ * The merge happens only if both parameters are list elements of the same type (the same element name and the same class attributes).
  *
  * @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter The writer instance.
- * @param {module:engine/view/item~Item} firstList First element o compare.
- * @param {module:engine/view/item~Item} secondList Second parameter to compare.
- * @returns {module:engine/view/position~Position|null} Position after merge or `null` when there was no merge.
+ * @param {module:engine/view/item~Item} firstList The first element to compare.
+ * @param {module:engine/view/item~Item} secondList The second element to compare.
+ * @returns {module:engine/view/position~Position|null} The position after merge or `null` when there was no merge.
  */
 export function mergeViewLists( viewWriter, firstList, secondList ) {
 	// Check if two lists are going to be merged.
@@ -171,12 +171,12 @@ export function mergeViewLists( viewWriter, firstList, secondList ) {
 }
 
 /**
- * Helper function that for given `view.Position`, returns a `view.Position` that is after all `view.UIElement`s that
- * are after given position.
+ * Helper function that for a given `view.Position`, returns a `view.Position` that is after all `view.UIElement`s that
+ * are after the given position.
  *
  * For example:
  * `<container:p>foo^<ui:span></ui:span><ui:span></ui:span>bar</container:p>`
- * For position ^, a position before "bar" will be returned.
+ * For position ^, the position before "bar" will be returned.
  *
  * @param {module:engine/view/position~Position} viewPosition
  * @returns {module:engine/view/position~Position}
@@ -186,14 +186,14 @@ export function positionAfterUiElements( viewPosition ) {
 }
 
 /**
- * Helper function that seeks for a previous list item sibling of given model item which meets given criteria
- * passed by an options object.
+ * Helper function that searches for a previous list item sibling of a given model item that meets the given criteria
+ * passed by the options object.
  *
  * @param {module:engine/model/item~Item} modelItem
  * @param {Object} options Search criteria.
- * @param {Boolean} [options.sameIndent=false] Whether sought sibling should have same indent.
- * @param {Boolean} [options.smallerIndent=false] Whether sought sibling should have smaller indent.
- * @param {Number} [options.listIndent] The reference indent.
+ * @param {Boolean} [options.sameIndent=false] Whether the sought sibling should have the same indentation.
+ * @param {Boolean} [options.smallerIndent=false] Whether the sought sibling should have a smaller indentation.
+ * @param {Number} [options.listIndent] The reference indentation.
  * @returns {module:engine/model/item~Item|null}
  */
 export function getSiblingListItem( modelItem, options ) {
@@ -227,10 +227,10 @@ export function findInRange( range, comparator ) {
 }
 
 /**
- * Helper method for creating an UI button and linking it with an appropriate command.
+ * Helper method for creating a UI button and linking it with an appropriate command.
  *
  * @private
- * @param {module:core/editor/editor~Editor} editor The editor instance to which UI component will be added.
+ * @param {module:core/editor/editor~Editor} editor The editor instance to which the UI component will be added.
  * @param {String} commandName The name of the command.
  * @param {Object} label The button label.
  * @param {String} icon The source of the icon.