Merge pull request #17518 from ckeditor/ck/17490-docs

Docs: Updated API docs and inline comments.

packages/ckeditor5-engine/src/conversion/upcastdispatcher.ts

@@ -499,6 +499,8 @@ export default class UpcastDispatcher extends /* #__PURE__ */ EmitterMixin() {
 	 * as some elements might have become empty after other empty elements were removed from them.
 	 */
 	private _removeEmptyElements(): void {
+		// For every parent, prepare an array of children (empty elements) to remove from it.
+		// Then, in next step, we will remove all children together, which is faster than removing them one by one.
 		const toRemove = new Map<ModelElement | ModelDocumentFragment, Array<ModelElement>>();
 
 		for ( const element of this._splitParts.keys() ) {

packages/ckeditor5-engine/src/model/documentfragment.ts

@@ -345,6 +345,10 @@ export default class DocumentFragment extends TypeCheckable implements Iterable<
 	 * Removes children nodes provided as an array and sets
 	 * the {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
 	 *
+	 * These nodes do not need to be direct siblings.
+	 *
+	 * This method is faster than removing nodes one by one, as it recalculates offsets only once.
+	 *
 	 * @internal
 	 * @param nodes Array of nodes.
 	 */

packages/ckeditor5-engine/src/model/element.ts

@@ -288,6 +288,10 @@ export default class Element extends Node {
 	 * Removes children nodes provided as an array and sets
 	 * the {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
 	 *
+	 * These nodes do not need to be direct siblings.
+	 *
+	 * This method is faster than removing nodes one by one, as it recalculates offsets only once.
+	 *
 	 * @internal
 	 * @param nodes Array of nodes.
 	 */

packages/ckeditor5-engine/src/model/nodelist.ts

@@ -231,7 +231,9 @@ export default class NodeList implements Iterable<Node> {
 	}
 
 	/**
-	 * Removes children nodes provided as an array.
+	 * Removes children nodes provided as an array. These nodes do not need to be direct siblings.
+	 *
+	 * This method is faster than removing nodes one by one, as it recalculates offsets only once.
 	 *
 	 * @internal
 	 * @param nodes Array of nodes.