diff --git a/modules/ve/dm/ve.dm.Node.js b/modules/ve/dm/ve.dm.Node.js
index b2d2ce63f6..5d6e0ea3ec 100644
--- a/modules/ve/dm/ve.dm.Node.js
+++ b/modules/ve/dm/ve.dm.Node.js
@@ -92,6 +92,22 @@ ve.dm.Node.static.matchFunction = null;
  * This function is only called if this node "won" the matching for the DOM element, so domElement
  * will match this node's matching rule.
  *
+ * This function is allowed to return a content element when context indicates that a non-content
+ * element is expected or vice versa. If that happens, the converter deals with it in the following way:
+ *
+ * - if a non-content element is expected but a content element is returned:
+ *     - open a wrapper paragraph
+ *     - put the returned element in the wrapper
+ * - if a content element is expected but a non-content element is returned:
+ *     - if we are in a wrapper paragraph:
+ *         - if we can close the wrapper:
+ *             - close the wrapper
+ *             - insert the returned element right after the end of the wrapper
+ *         - if we can't close the wrapper:
+ *             - alienate the element
+ *     - if we aren't in a wrapper paragraph:
+ *         - alienate the element
+ *
  * The returned linear model element must have a type property set to a registered node name
  * (usually the node's .static.name, but that's not required). It may optionally have an attributes
  * property set to an object with key-value pairs. Any other properties are not allowed.
@@ -99,9 +115,15 @@ ve.dm.Node.static.matchFunction = null;
  * @static
  * @method
  * @param {HTMLElement} domElement DOM element to convert
- * @returns {Object} Linear model element
+ * @param {Object} context Object describing the current state of the converter
+ * @param {boolean} context.expectingContent Whether this function is expected to return a content element
+ * @param {boolean} context.inWrapper Whether this element is in a wrapper paragraph generated by the converter;
+ *  can only be true if context.expectingContent is also true
+ * @param {boolean} context.canCloseWrapper Whether the current wrapper paragraph can be closed;
+ *  can only be true if context.inWrapper is also true
+ * @returns {Object|null} Linear model element, or null to alienate
  */
-ve.dm.Node.static.toDataElement = function ( /*domElement*/ ) {
+ve.dm.Node.static.toDataElement = function ( /*domElement, context*/ ) {
 	throw new Error( 've.dm.Node subclass must implement toDataElement' );
 };