@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.0

package/src/view/range.js

@@ -23,24 +23,12 @@ export default class Range extends TypeCheckable {
      *
      * **Note:** Constructor creates it's own {@link module:engine/view/position~Position} instances basing on passed values.
      *
-     * @param {module:engine/view/position~Position} start Start position.
-     * @param {module:engine/view/position~Position} [end] End position. If not set, range will be collapsed at the `start` position.
+     * @param start Start position.
+     * @param end End position. If not set, range will be collapsed at the `start` position.
      */
     constructor(start, end = null) {
         super();
-        /**
-         * Start position.
-         *
-         * @readonly
-         * @member {module:engine/view/position~Position}
-         */
         this.start = start.clone();
-        /**
-         * End position.
-         *
-         * @readonly
-         * @member {module:engine/view/position~Position}
-         */
         this.end = end ? end.clone() : start.clone();
     }
     /**
@@ -53,16 +41,12 @@ export default class Range extends TypeCheckable {
      * This iterator uses {@link module:engine/view/treewalker~TreeWalker TreeWalker} with `boundaries` set to this range and
      * `ignoreElementEnd` option
      * set to `true`.
-     *
-     * @returns {Iterable.<module:engine/view/treewalker~TreeWalkerValue>}
      */
     *[Symbol.iterator]() {
         yield* new TreeWalker({ boundaries: this, ignoreElementEnd: true });
     }
     /**
      * Returns whether the range is collapsed, that is it start and end positions are equal.
-     *
-     * @type {Boolean}
      */
     get isCollapsed() {
         return this.start.isEqual(this.end);
@@ -70,16 +54,12 @@ export default class Range extends TypeCheckable {
     /**
      * Returns whether this range is flat, that is if {@link module:engine/view/range~Range#start start} position and
      * {@link module:engine/view/range~Range#end end} position are in the same {@link module:engine/view/position~Position#parent parent}.
-     *
-     * @type {Boolean}
      */
     get isFlat() {
         return this.start.parent === this.end.parent;
     }
     /**
      * Range root element.
-     *
-     * @type {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment}
      */
     get root() {
         return this.start.root;
@@ -90,8 +70,10 @@ export default class Range extends TypeCheckable {
      *
      * For example:
      *
-     *		<p>Foo</p><p><b>{Bar}</b></p> -> <p>Foo</p>[<p><b>Bar</b>]</p>
-     *		<p><b>foo</b>{bar}<span></span></p> -> <p><b>foo[</b>bar<span></span>]</p>
+     * ```html
+     * <p>Foo</p><p><b>{Bar}</b></p> -> <p>Foo</p>[<p><b>Bar</b>]</p>
+     * <p><b>foo</b>{bar}<span></span></p> -> <p><b>foo[</b>bar<span></span>]</p>
+     * ```
      *
      * Note that in the sample above:
      *
@@ -99,7 +81,7 @@ export default class Range extends TypeCheckable {
      * - `<b>` have type of {@link module:engine/view/attributeelement~AttributeElement},
      * - `<span>` have type of {@link module:engine/view/uielement~UIElement}.
      *
-     * @returns {module:engine/view/range~Range} Enlarged range.
+     * @returns Enlarged range.
      */
     getEnlarged() {
         let start = this.start.getLastMatchingPosition(enlargeTrimSkip, { direction: 'backward' });
@@ -119,8 +101,10 @@ export default class Range extends TypeCheckable {
      *
      * For example:
      *
-     *		<p>Foo</p>[<p><b>Bar</b>]</p> -> <p>Foo</p><p><b>{Bar}</b></p>
-     *		<p><b>foo[</b>bar<span></span>]</p> -> <p><b>foo</b>{bar}<span></span></p>
+     * ```html
+     * <p>Foo</p>[<p><b>Bar</b>]</p> -> <p>Foo</p><p><b>{Bar}</b></p>
+     * <p><b>foo[</b>bar<span></span>]</p> -> <p><b>foo</b>{bar}<span></span></p>
+     * ```
      *
      * Note that in the sample above:
      *
@@ -128,7 +112,7 @@ export default class Range extends TypeCheckable {
      * - `<b>` have type of {@link module:engine/view/attributeelement~AttributeElement},
      * - `<span>` have type of {@link module:engine/view/uielement~UIElement}.
      *
-     * @returns {module:engine/view/range~Range} Shrink range.
+     * @returns Shrunk range.
      */
     getTrimmed() {
         let start = this.start.getLastMatchingPosition(enlargeTrimSkip);
@@ -150,8 +134,8 @@ export default class Range extends TypeCheckable {
     /**
      * Two ranges are equal if their start and end positions are equal.
      *
-     * @param {module:engine/view/range~Range} otherRange Range to compare with.
-     * @returns {Boolean} `true` if ranges are equal, `false` otherwise
+     * @param otherRange Range to compare with.
+     * @returns `true` if ranges are equal, `false` otherwise
      */
     isEqual(otherRange) {
         return this == otherRange || (this.start.isEqual(otherRange.start) && this.end.isEqual(otherRange.end));
@@ -159,9 +143,8 @@ export default class Range extends TypeCheckable {
     /**
      * Checks whether this range contains given {@link module:engine/view/position~Position position}.
      *
-     * @param {module:engine/view/position~Position} position Position to check.
-     * @returns {Boolean} `true` if given {@link module:engine/view/position~Position position} is contained in this range,
-     * `false` otherwise.
+     * @param position Position to check.
+     * @returns `true` if given {@link module:engine/view/position~Position position} is contained in this range, `false` otherwise.
      */
     containsPosition(position) {
         return position.isAfter(this.start) && position.isBefore(this.end);
@@ -169,11 +152,11 @@ export default class Range extends TypeCheckable {
     /**
      * Checks whether this range contains given {@link module:engine/view/range~Range range}.
      *
-     * @param {module:engine/view/range~Range} otherRange Range to check.
-     * @param {Boolean} [loose=false] Whether the check is loose or strict. If the check is strict (`false`), compared range cannot
+     * @param otherRange Range to check.
+     * @param loose Whether the check is loose or strict. If the check is strict (`false`), compared range cannot
      * start or end at the same position as this range boundaries. If the check is loose (`true`), compared range can start, end or
      * even be equal to this range. Note that collapsed ranges are always compared in strict mode.
-     * @returns {Boolean} `true` if given {@link module:engine/view/range~Range range} boundaries are contained by this range, `false`
+     * @returns `true` if given {@link module:engine/view/range~Range range} boundaries are contained by this range, `false`
      * otherwise.
      */
     containsRange(otherRange, loose = false) {
@@ -191,29 +174,31 @@ export default class Range extends TypeCheckable {
      *
      * Examples:
      *
-     *		let foo = downcastWriter.createText( 'foo' );
-     *		let img = downcastWriter.createContainerElement( 'img' );
-     *		let bar = downcastWriter.createText( 'bar' );
-     *		let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
-     *
-     *		let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
-     *		let otherRange = view.createRange( // "oo", img, "ba" are in range.
-     *			view.createPositionAt( foo, 1 ),
-     *			view.createPositionAt( bar, 2 )
-     *		);
-     *		let transformed = range.getDifference( otherRange );
-     *		// transformed array has no ranges because `otherRange` contains `range`
-     *
-     *		otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.
-     *		transformed = range.getDifference( otherRange );
-     *		// transformed array has one range: from ( p, 2 ) to ( bar, 1 )
-     *
-     *		otherRange = view.createRange( view.createPositionAt( p, 1 ), view.createPositionAt( p, 2 ) ); // img is in range.
-     *		transformed = range.getDifference( otherRange );
-     *		// transformed array has two ranges: from ( foo, 1 ) to ( p, 1 ) and from ( p, 2 ) to ( bar, 1 )
-     *
-     * @param {module:engine/view/range~Range} otherRange Range to differentiate against.
-     * @returns {Array.<module:engine/view/range~Range>} The difference between ranges.
+     * ```ts
+     * let foo = downcastWriter.createText( 'foo' );
+     * let img = downcastWriter.createContainerElement( 'img' );
+     * let bar = downcastWriter.createText( 'bar' );
+     * let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
+     *
+     * let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
+     * let otherRange = view.createRange( // "oo", img, "ba" are in range.
+     * 	view.createPositionAt( foo, 1 ),
+     * 	view.createPositionAt( bar, 2 )
+     * );
+     * let transformed = range.getDifference( otherRange );
+     * // transformed array has no ranges because `otherRange` contains `range`
+     *
+     * otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.
+     * transformed = range.getDifference( otherRange );
+     * // transformed array has one range: from ( p, 2 ) to ( bar, 1 )
+     *
+     * otherRange = view.createRange( view.createPositionAt( p, 1 ), view.createPositionAt( p, 2 ) ); // img is in range.
+     * transformed = range.getDifference( otherRange );
+     * // transformed array has two ranges: from ( foo, 1 ) to ( p, 1 ) and from ( p, 2 ) to ( bar, 1 )
+     * ```
+     *
+     * @param otherRange Range to differentiate against.
+     * @returns The difference between ranges.
      */
     getDifference(otherRange) {
         const ranges = [];
@@ -242,20 +227,22 @@ export default class Range extends TypeCheckable {
      *
      * Examples:
      *
-     *		let foo = downcastWriter.createText( 'foo' );
-     *		let img = downcastWriter.createContainerElement( 'img' );
-     *		let bar = downcastWriter.createText( 'bar' );
-     *		let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
+     * ```ts
+     * let foo = downcastWriter.createText( 'foo' );
+     * let img = downcastWriter.createContainerElement( 'img' );
+     * let bar = downcastWriter.createText( 'bar' );
+     * let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] );
      *
-     *		let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
-     *		let otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.
-     *		let transformed = range.getIntersection( otherRange ); // range from ( foo, 1 ) to ( p, 2 ).
+     * let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range.
+     * let otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range.
+     * let transformed = range.getIntersection( otherRange ); // range from ( foo, 1 ) to ( p, 2 ).
      *
-     *		otherRange = view.createRange( view.createPositionAt( bar, 1 ), view.createPositionAt( bar, 3 ); "ar" is in range.
-     *		transformed = range.getIntersection( otherRange ); // null - no common part.
+     * otherRange = view.createRange( view.createPositionAt( bar, 1 ), view.createPositionAt( bar, 3 ); "ar" is in range.
+     * transformed = range.getIntersection( otherRange ); // null - no common part.
+     * ```
      *
-     * @param {module:engine/view/range~Range} otherRange Range to check for intersection.
-     * @returns {module:engine/view/range~Range|null} A common part of given ranges or `null` if ranges have no common part.
+     * @param otherRange Range to check for intersection.
+     * @returns A common part of given ranges or `null` if ranges have no common part.
      */
     getIntersection(otherRange) {
         if (this.isIntersecting(otherRange)) {
@@ -281,12 +268,7 @@ export default class Range extends TypeCheckable {
     /**
      * Creates a {@link module:engine/view/treewalker~TreeWalker TreeWalker} instance with this range as a boundary.
      *
-     * @param {Object} options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
-     * @param {module:engine/view/position~Position} [options.startPosition]
-     * @param {Boolean} [options.singleCharacters=false]
-     * @param {Boolean} [options.shallow=false]
-     * @param {Boolean} [options.ignoreElementEnd=false]
-     * @returns {module:engine/view/treewalker~TreeWalker}
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
      */
     getWalker(options = {}) {
         options.boundaries = this;
@@ -295,8 +277,6 @@ export default class Range extends TypeCheckable {
     /**
      * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
      * which is a common ancestor of range's both ends (in which the entire range is contained).
-     *
-     * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null}
      */
     getCommonAncestor() {
         return this.start.getCommonAncestor(this.end);
@@ -305,8 +285,6 @@ export default class Range extends TypeCheckable {
      * Returns an {@link module:engine/view/element~Element Element} contained by the range.
      * The element will be returned when it is the **only** node within the range and **fully–contained**
      * at the same time.
-     *
-     * @returns {module:engine/view/element~Element|null}
      */
     getContainedElement() {
         if (this.isCollapsed) {
@@ -336,8 +314,6 @@ export default class Range extends TypeCheckable {
     }
     /**
      * Clones this range.
-     *
-     * @returns {module:engine/view/range~Range}
      */
     clone() {
         return new Range(this.start, this.end);
@@ -353,8 +329,7 @@ export default class Range extends TypeCheckable {
      * You may specify additional options for the tree walker. See {@link module:engine/view/treewalker~TreeWalker} for
      * a full list of available options.
      *
-     * @param {Object} options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
-     * @returns {Iterable.<module:engine/view/item~Item>}
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
      */
     *getItems(options = {}) {
         options.boundaries = this;
@@ -374,8 +349,7 @@ export default class Range extends TypeCheckable {
      * You may specify additional options for the tree walker. See {@link module:engine/view/treewalker~TreeWalker} for
      * a full list of available options.
      *
-     * @param {Object} options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
-     * @returns {Iterable.<module:engine/view/position~Position>}
+     * @param options Object with configuration options. See {@link module:engine/view/treewalker~TreeWalker}.
      */
     *getPositions(options = {}) {
         options.boundaries = this;
@@ -388,8 +362,8 @@ export default class Range extends TypeCheckable {
     /**
      * Checks and returns whether this range intersects with the given range.
      *
-     * @param {module:engine/view/range~Range} otherRange Range to compare with.
-     * @returns {Boolean} True if ranges intersect.
+     * @param otherRange Range to compare with.
+     * @returns True if ranges intersect.
      */
     isIntersecting(otherRange) {
         return this.start.isBefore(otherRange.end) && this.end.isAfter(otherRange.start);
@@ -397,14 +371,12 @@ export default class Range extends TypeCheckable {
     /**
      * Creates a range from the given parents and offsets.
      *
-     * @protected
-     * @param {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment} startElement Start position
-     * parent element.
-     * @param {Number} startOffset Start position offset.
-     * @param {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment} endElement End position
-     * parent element.
-     * @param {Number} endOffset End position offset.
-     * @returns {module:engine/view/range~Range} Created range.
+     * @internal
+     * @param startElement Start position parent element.
+     * @param startOffset Start position offset.
+     * @param endElement End position parent element.
+     * @param endOffset End position offset.
+     * @returns Created range.
      */
     static _createFromParentsAndOffsets(startElement, startOffset, endElement, endOffset) {
         return new this(new Position(startElement, startOffset), new Position(endElement, endOffset));
@@ -413,10 +385,9 @@ export default class Range extends TypeCheckable {
      * Creates a new range, spreading from specified {@link module:engine/view/position~Position position} to a position moved by
      * given `shift`. If `shift` is a negative value, shifted position is treated as the beginning of the range.
      *
-     * @protected
-     * @param {module:engine/view/position~Position} position Beginning of the range.
-     * @param {Number} shift How long the range should be.
-     * @returns {module:engine/view/range~Range}
+     * @internal
+     * @param position Beginning of the range.
+     * @param shift How long the range should be.
      */
     static _createFromPositionAndShift(position, shift) {
         const start = position;
@@ -427,9 +398,8 @@ export default class Range extends TypeCheckable {
      * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
      * that element and ends after the last child of that element.
      *
-     * @protected
-     * @param {module:engine/view/element~Element} element Element which is a parent for the range.
-     * @returns {module:engine/view/range~Range}
+     * @internal
+     * @param element Element which is a parent for the range.
      */
     static _createIn(element) {
         return this._createFromParentsAndOffsets(element, 0, element, element.childCount);
@@ -437,34 +407,21 @@ export default class Range extends TypeCheckable {
     /**
      * Creates a range that starts before given {@link module:engine/view/item~Item view item} and ends after it.
      *
-     * @protected
-     * @param {module:engine/view/item~Item} item
-     * @returns {module:engine/view/range~Range}
+     * @internal
      */
     static _createOn(item) {
         const size = item.is('$textProxy') ? item.offsetSize : 1;
         return this._createFromPositionAndShift(Position._createBefore(item), size);
     }
 }
-/**
- * Checks whether this object is of the given type.
- *
- *		range.is( 'range' ); // -> true
- *		range.is( 'view:range' ); // -> true
- *
- *		range.is( 'model:range' ); // -> false
- *		range.is( 'element' ); // -> false
- *		range.is( 'selection' ); // -> false
- *
- * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 Range.prototype.is = function (type) {
     return type === 'range' || type === 'view:range';
 };
-// Function used by getEnlarged and getTrimmed methods.
+/**
+ * Function used by getEnlarged and getTrimmed methods.
+ */
 function enlargeTrimSkip(value) {
     if (value.item.is('attributeElement') || value.item.is('uiElement')) {
         return true;

package/src/view/rawelement.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module engine/view/rawelement
+ */
+import Element, { type ElementAttributes } from './element';
+import Node from './node';
+import type Document from './document';
+import type DomConverter from './domconverter';
+import type Item from './item';
+type DomElement = globalThis.HTMLElement;
+/**
+ * The raw element class.
+ *
+ * The raw elements work as data containers ("wrappers", "sandboxes") but their children are not managed or
+ * even recognized by the editor. This encapsulation allows integrations to maintain custom DOM structures
+ * in the editor content without, for instance, worrying about compatibility with other editor features.
+ * Raw elements are a perfect tool for integration with external frameworks and data sources.
+ *
+ * Unlike {@link module:engine/view/uielement~UIElement UI elements}, raw elements act like real editor
+ * content (similar to {@link module:engine/view/containerelement~ContainerElement} or
+ * {@link module:engine/view/emptyelement~EmptyElement}), they are considered by the editor selection and
+ * {@link module:widget/utils~toWidget they can work as widgets}.
+ *
+ * To create a new raw element, use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement `downcastWriter#createRawElement()`} method.
+ */
+export default class RawElement extends Element {
+    /**
+     * Creates a new instance of a raw element.
+     *
+     * Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} when the `children`
+     * parameter is passed to inform that the usage of `RawElement` is incorrect (adding child nodes to `RawElement` is forbidden).
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#createRawElement
+     * @internal
+     * @param document The document instance to which this element belongs.
+     * @param name Node name.
+     * @param attrs Collection of attributes.
+     * @param children A list of nodes to be inserted into created element.
+     */
+    constructor(document: Document, name: string, attrs?: ElementAttributes, children?: Node | Iterable<Node>);
+    /**
+     * Overrides the {@link module:engine/view/element~Element#_insertChild} method.
+     * Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} to prevent
+     * adding any child nodes to a raw element.
+     *
+     * @internal
+     */
+    _insertChild(index: number, items: Item | Iterable<Item>): number;
+    /**
+     * This allows rendering the children of a {@link module:engine/view/rawelement~RawElement} on the DOM level.
+     * This method is called by the {@link module:engine/view/domconverter~DomConverter} with the raw DOM element
+     * passed as an argument, leaving the number and shape of the children up to the integrator.
+     *
+     * This method **must be defined** for the raw element to work:
+     *
+     * ```ts
+     * const myRawElement = downcastWriter.createRawElement( 'div' );
+     *
+     * myRawElement.render = function( domElement, domConverter ) {
+     * 	domConverter.setContentOf( domElement, '<b>This is the raw content of myRawElement.</b>' );
+     * };
+     * ```
+     *
+     * @param domElement The native DOM element representing the raw view element.
+     * @param domConverter Instance of the DomConverter used to optimize the output.
+     */
+    render(domElement: DomElement, domConverter: DomConverter): void;
+}
+export {};

package/src/view/rawelement.js

@@ -2,6 +2,7 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * @module engine/view/rawelement
  */
@@ -23,8 +24,6 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  *
  * To create a new raw element, use the
  * {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement `downcastWriter#createRawElement()`} method.
- *
- * @extends module:engine/view/element~Element
  */
 export default class RawElement extends Element {
     /**
@@ -34,21 +33,15 @@ export default class RawElement extends Element {
      * parameter is passed to inform that the usage of `RawElement` is incorrect (adding child nodes to `RawElement` is forbidden).
      *
      * @see module:engine/view/downcastwriter~DowncastWriter#createRawElement
-     * @protected
-     * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
-     * @param {String} name A node name.
-     * @param {Object|Iterable} [attrs] The collection of attributes.
-     * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
-     * A list of nodes to be inserted into the created element.
+     * @internal
+     * @param document The document instance to which this element belongs.
+     * @param name Node name.
+     * @param attrs Collection of attributes.
+     * @param children A list of nodes to be inserted into created element.
      */
-    constructor(...args) {
-        super(...args);
-        /**
-         * Returns `null` because filler is not needed for raw elements.
-         *
-         * @method #getFillerOffset
-         * @returns {null} Always returns null.
-         */
+    constructor(document, name, attrs, children) {
+        super(document, name, attrs, children);
+        // Returns `null` because filler is not needed for raw elements.
         this.getFillerOffset = getFillerOffset;
     }
     /**
@@ -56,7 +49,7 @@ export default class RawElement extends Element {
      * Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} to prevent
      * adding any child nodes to a raw element.
      *
-     * @protected
+     * @internal
      */
     _insertChild(index, items) {
         if (items && (items instanceof Node || Array.from(items).length > 0)) {
@@ -69,35 +62,28 @@ export default class RawElement extends Element {
         }
         return 0;
     }
-    render() { }
+    /**
+     * This allows rendering the children of a {@link module:engine/view/rawelement~RawElement} on the DOM level.
+     * This method is called by the {@link module:engine/view/domconverter~DomConverter} with the raw DOM element
+     * passed as an argument, leaving the number and shape of the children up to the integrator.
+     *
+     * This method **must be defined** for the raw element to work:
+     *
+     * ```ts
+     * const myRawElement = downcastWriter.createRawElement( 'div' );
+     *
+     * myRawElement.render = function( domElement, domConverter ) {
+     * 	domConverter.setContentOf( domElement, '<b>This is the raw content of myRawElement.</b>' );
+     * };
+     * ```
+     *
+     * @param domElement The native DOM element representing the raw view element.
+     * @param domConverter Instance of the DomConverter used to optimize the output.
+     */
+    render(domElement, domConverter) { }
 }
-/**
- * Checks whether this object is of the given type or name.
- *
- *		rawElement.is( 'rawElement' ); // -> true
- *		rawElement.is( 'element' ); // -> true
- *		rawElement.is( 'node' ); // -> true
- *		rawElement.is( 'view:rawElement' ); // -> true
- *		rawElement.is( 'view:element' ); // -> true
- *		rawElement.is( 'view:node' ); // -> true
- *
- *		rawElement.is( 'model:element' ); // -> false
- *		rawElement.is( 'documentFragment' ); // -> false
- *
- * Assuming that the object being checked is a raw element, you can also check its
- * {@link module:engine/view/rawelement~RawElement#name name}:
- *
- *		rawElement.is( 'img' ); // -> true if this is an img element
- *		rawElement.is( 'rawElement', 'img' ); // -> same as above
- *		text.is( 'img' ); -> false
- *
- * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
- *
- * @param {String} type The type to check when the `name` parameter is present.
- * Otherwise, it acts like the `name` parameter.
- * @param {String} [name] The element name.
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 RawElement.prototype.is = function (type, name) {
     if (!name) {
         return type === 'rawElement' || type === 'view:rawElement' ||
@@ -111,9 +97,9 @@ RawElement.prototype.is = function (type, name) {
             type === 'element' || type === 'view:element');
     }
 };
-// Returns `null` because block filler is not needed for raw elements.
-//
-// @returns {null}
+/**
+ * Returns `null` because block filler is not needed for raw elements.
+ */
 function getFillerOffset() {
     return null;
 }