浏览代码

Added missing API docs.

Oskar Wróbel 6 年之前
父节点
当前提交
fa7646942e

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

@@ -98,6 +98,9 @@ export function modelViewRemove( model ) {
  * by breaking view elements and changing their name. Next {@link module:list/converters~modelViewMergeAfterChangeType}
  * converter will try 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.
+ *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
  * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.

+ 3 - 0
packages/ckeditor5-list/src/todolist.js

@@ -15,6 +15,9 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 /**
  * The todo list feature.
  *
+ * This is a "glue" plugin which loads the {@link module:list/todolistediting~TodoListEditing todo list editing feature}
+ * and {@link module:list/todolistui~TodoListUI list UI feature}.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class List extends Plugin {

+ 20 - 9
packages/ckeditor5-list/src/todolistcheckcommand.js

@@ -16,25 +16,27 @@ const attributeKey = 'todoListChecked';
  */
 export default class TodoListCheckCommand extends Command {
 	/**
-	 * @param {module:core/editor/editor~Editor} editor
+	 * @inheritDoc
 	 */
 	constructor( editor ) {
 		super( editor );
 
-		this._selectedElements = [];
-
 		/**
-		 * Flag indicating whether the command is active. The command is active when the
-		 * {@link module:engine/model/selection~Selection#hasAttribute selection has the attribute} which means that:
-		 *
-		 * * If the selection is not empty – That the attribute is set on the first node in the selection that allows this attribute.
-		 * * If the selection is empty – That the selection has the attribute itself (which means that newly typed
-		 * text will have this attribute, too).
+		 * 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 todo list item.
 		 *
 		 * @observable
 		 * @readonly
 		 * @member {Boolean} #value
 		 */
+
+		/**
+		 * List of todo list items selected by the {@link module:engine/model/selection~Selection}.
+		 *
+		 * @type {Array.<module:engine/model/element~Element>}
+		 * @private
+		 */
+		this._selectedElements = [];
 	}
 
 	/**
@@ -46,6 +48,12 @@ export default class TodoListCheckCommand extends Command {
 		this.isEnabled = !!this._selectedElements.length;
 	}
 
+	/**
+	 * Gets all todo list items selected by the {@link module:engine/model/selection~Selection}.
+	 *
+	 * @private
+	 * @returns {Array.<module:engine/model/element~Element>}
+	 */
 	_getSelectedItems() {
 		const model = this.editor.model;
 		const schema = model.schema;
@@ -67,6 +75,9 @@ export default class TodoListCheckCommand extends Command {
 		return elements;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	execute() {
 		this.editor.model.change( writer => {
 			for ( const element of this._selectedElements ) {

+ 71 - 0
packages/ckeditor5-list/src/todolistconverters.js

@@ -13,6 +13,13 @@ 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.
+ *
+ * It converts `listItem` model element to an unordered list with {@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}.
+ *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert
  * @param {module:engine/model/model~Model} model Model instance.
  * @returns {Function} Returns a conversion callback.
@@ -47,6 +54,12 @@ export function modelViewInsertion( model ) {
 }
 
 /**
+ * A model-to-view converter for model `$text` element inside a todo list item.
+ *
+ * It takes care of creating text after the {@link module:engine/view/uielement~UIElement checkbox UI element}.
+ *
+ * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
+ *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert
  * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
@@ -67,10 +80,19 @@ export function modelViewTextInsertion( evt, data, conversionApi ) {
 	const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
 	const viewText = viewWriter.createText( data.item.data );
 
+	// Be sure text is created after the UIElement, so if it is a first text node inside a `listItem` element
+	// it has to be moved after the first node in the view list item.
+	//
+	// model: <listItem listtype="todo">[foo]</listItem>
+	// view: <li>^<checkbox/></li> -> <li><checkbox/>foo</li>
 	viewWriter.insert( viewPosition.offset ? viewPosition : viewPosition.getShiftedBy( 1 ), viewText );
 }
 
 /**
+ * A model-to-view converter for `listItem` model element insertion.
+ *
+ * It is used by {@link module:engine/controller/datacontroller~DataController}.
+ *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert
  * @param {module:engine/model/model~Model} model Model instance.
  * @returns {Function} Returns a conversion callback.
@@ -119,6 +141,10 @@ export function dataModelViewInsertion( model ) {
 }
 
 /**
+ * A model-to-view converter for model `$text` element inside a todo list item.
+ *
+ * It is used by {@link module:engine/controller/datacontroller~DataController}.
+ *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert
  * @param {module:utils/eventinfo~EventInfo} evt An object containing information about the fired event.
  * @param {Object} data Additional information about the change.
@@ -147,6 +173,13 @@ export function dataModelViewTextInsertion( evt, data, conversionApi ) {
 }
 
 /**
+ * A view-to-model converter for 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 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.
@@ -177,6 +210,16 @@ export function dataViewModelCheckmarkInsertion( evt, data, conversionApi ) {
 }
 
 /**
+ * A model-to-view converter for `listType` attribute change on `listItem` model element.
+ *
+ * This change means that `<li>` elements parent changes to `<ul class="todo-list">` and
+ * {@link module:engine/view/uielement~UIElement checkbox UI element} is added at the beginning of the list item element.
+ *
+ * This converter is preceded by {@link module:list/converters~modelViewChangeType} and followed by
+ * {@link module:list/converters~modelViewMergeAfterChangeType} to handle splitting and merging surrounding lists of the same type.
+ *
+ * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
+ *
  * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
  * @param {module:engine/model/model~Model} model Model instance.
  * @returns {Function} Returns a conversion callback.
@@ -196,6 +239,12 @@ export function modelViewChangeType( model ) {
 }
 
 /**
+ * A model-to-view converter for `todoListChecked` attribute change on `listItem` model element.
+ *
+ * It marks {@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 {module:engine/model/model~Model} model Model instance.
  * @returns {Function} Returns a conversion callback.
@@ -218,6 +267,13 @@ export function modelViewChangeChecked( model ) {
 	};
 }
 
+// Injects checkbox element inside a view list item and adds `todo-list` class to the parent list element.
+//
+// @private
+// @param {module:engine/model/item~Item} modelItem
+// @param {module:engine/view/item~Item} ViewItem
+// @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter
+// @param {module:engine/model/model~Model} model
 function addTodoElementsToListItem( modelItem, viewItem, viewWriter, model ) {
 	const isChecked = !!modelItem.getAttribute( 'todoListChecked' );
 	const checkmarkElement = createCheckmarkElement( modelItem, viewWriter, isChecked, model );
@@ -226,12 +282,27 @@ function addTodoElementsToListItem( modelItem, viewItem, viewWriter, model ) {
 	viewWriter.insert( viewWriter.createPositionAt( viewItem, 0 ), checkmarkElement );
 }
 
+// Removes checkbox element from a view list item and removes `todo-list` class from the parent list element.
+//
+// @private
+// @param {module:engine/model/item~Item} modelItem
+// @param {module:engine/view/item~Item} ViewItem
+// @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter
+// @param {module:engine/model/model~Model} model
 function removeTodoElementsFromListItem( modelItem, viewItem, viewWriter, model ) {
 	viewWriter.removeClass( 'todo-list', viewItem.parent );
 	viewWriter.remove( viewItem.getChild( 0 ) );
 	model.change( writer => writer.removeAttribute( 'todoListChecked', modelItem ) );
 }
 
+// Creates checkbox UI element.
+//
+// @private
+// @param {module:engine/model/item~Item} modelItem
+// @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter
+// @param {Boolean} isChecked
+// @param {module:engine/model/model~Model} model
+// @returns {module:view/uielement~UIElement}
 function createCheckmarkElement( modelItem, viewWriter, isChecked, model ) {
 	const uiElement = viewWriter.createUIElement(
 		'label',

+ 12 - 0
packages/ckeditor5-list/src/todolistediting.js

@@ -26,6 +26,11 @@ import {
 import { findInRange } from './utils';
 
 /**
+ * The engine of the todo list feature. It handles creating, editing and removing todo lists and its items.
+ *
+ * It registers all functionalities of {@link module:list/listediting~ListEditing list editing plugin} and extends
+ * it by `'todoList'` command.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class TodoListEditing extends Plugin {
@@ -123,6 +128,8 @@ export default class TodoListEditing extends Plugin {
 	}
 }
 
+// Moves all uiElements in the todo list item after the checkmark element.
+//
 // @private
 // @param {module:engine/view/downcastwriter~DowncastWriter} writer
 // @param {Array.<module:engine/view/uielement~UIElement>} uiElements
@@ -152,6 +159,8 @@ function moveUIElementsAfterCheckmark( writer, uiElements ) {
 	return hasChanged;
 }
 
+// Moves selection in the todo list item after the checkmark element.
+//
 // @private
 // @param {module:engine/view/downcastwriter~DowncastWriter} writer
 // @param {module:engine/view/documentselection~DocumentSelection} selection
@@ -188,6 +197,9 @@ 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.
+//
 // @private
 // @param {Function} stopKeyEvent
 // @param {module:engine/model/model~Model} model

+ 3 - 0
packages/ckeditor5-list/src/todolistui.js

@@ -15,6 +15,9 @@ import '../theme/list.css';
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 
 /**
+ * The todo list UI feature. It introduces the `'todoList'` button that
+ * allow to convert elements to and from list items and indent or outdent them.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class TodoListUI extends Plugin {