Merge pull request #826 from wordpress-mobile/update/add-comments-to-…

…clarify-jsdom-patches

Add comments to clarify functions in jsdom-patches file.

src/globals.js

@@ -16,7 +16,14 @@ import { createElement } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-// Import for side-effects: Patches for jsdom-jscore, details commented in file.
+
+/**
+ * Import for side-effects: Patches for jsdom-jscore, mostly to implement
+ * functions that are called from Gutenberg code paths, where a more full DOM
+ * implementation is expected (in the browser environment).
+ *
+ * More details are available within the comments in the file.
+ */
 import './jsdom-patches';
 
 global.wp = {

src/jsdom-patches.js

@@ -37,15 +37,35 @@ const {
 	DOCUMENT_FRAGMENT_NODE,
 } = Node;
 
-// Simple recursive implementation of Node.contains method
+/**
+ * Simple recursive implementation of Node.contains method
+ * @param {number} otherNode Another node (may be the same node).
+ * @return {boolean} true if otherNode is a descendant of this node, or is this
+ * node, false otherwise.
+ *
+ * This function is necessary in the mobile environment, because there are code
+ * paths that make use of functions in the Gutenberg (web) project, which has
+ * expectation that this is implemented (as it is in the browser environment).
+ */
 Node.prototype.contains = function( otherNode ) {
 	return this === otherNode ||
 		Array.prototype.some.call( this._childNodes, ( childNode ) => {
 			return childNode.contains( otherNode );
 		} );
 };
 
-// copied from jsdom-jscore, but without WRONG_DOCUMENT_ERR exception
+/**
+ * Copy of insertBefore function from jsdom-jscore, WRONG_DOCUMENT_ERR exception
+ * disabled.
+ * @param {Object} newChild The node to be insterted.
+ * @param {Object} refChild The node before which newChild is inserted.
+ * @return {Object} the newly inserted child node
+ *
+ * This function is modified here to remove the WRONG_DOCUMENT_ERR exception
+ * that is no longer part of the DOM spec for this function.
+ * see: https://github.com/jsdom/jsdom/issues/717 for more information, * and:
+ * https://dom.spec.whatwg.org/#dom-node-insertbefore for the latest spec.
+ */
 Node.prototype.insertBefore = function( /* Node */ newChild, /* Node*/ refChild ) {
 	if ( this._readonly === true ) {
 		throw new core.DOMException( NO_MODIFICATION_ALLOWED_ERR, 'Attempting to modify a read-only node' );
@@ -118,6 +138,12 @@ Node.prototype.insertBefore = function( /* Node */ newChild, /* Node*/ refChild
 	return newChild;
 }; // raises(DOMException);
 
-// alias (polyfill not needed)
-// see: https://developer.mozilla.org/en-US/docs/Web/API/Element/matches#Polyfill
+/*
+ * This is merely an alias (polyfill not needed).
+ * see: https://developer.mozilla.org/en-US/docs/Web/API/Element/matches#Polyfill
+ *
+ * This function is necessary in the mobile environment, because there are code
+ * paths that make use of functions in the Gutenberg (web) project, which has
+ * expectation that this is implemented (as it is in the browser environment).
+ */
 Element.prototype.matches = Element.prototype.matchesSelector;