Add JSDoc

Rename xPathElements to getXPathElements
AdguardTeam · Aug 16, 2023 · bf846a7 · bf846a7
1 parent 0f4588e
commit bf846a7
Showing 1 changed file with 15 additions and 4 deletions.
diff --git a/src/scriptlets/xml-prune.js b/src/scriptlets/xml-prune.js
@@ -62,10 +62,14 @@ import {
  * 1. Remove `Period` tag whose `id` contains `pre-roll` and remove `duration` attribute from the `Period` tag
  *    by using XPath expression
  *
+ *     <!-- markdownlint-disable line-length -->
+ *
  *     ```adblock
  *     example.org#%#//scriptlet('xml-prune', 'xpath(//*[name()="Period"][contains(@id, "pre-roll") and contains(@id, "-ad-")] | //*[name()="Period"]/@duration)')
  *     ```
  *
+ *     <!-- markdownlint-enable line-length -->
+ *
  * 1. Call with no arguments will log response payload and URL at the console
  *
  *     ```adblock
@@ -101,7 +105,14 @@ export function xmlPrune(source, propsToRemove, optionalProp = '', urlToMatch =
     const XPATH_MARKER = 'xpath(';
     const isXpath = propsToRemove && propsToRemove.startsWith(XPATH_MARKER);
 
-    const xPathElements = (contextNode) => {
+    /**
+     * Checks if the document node from the XML document contains propsToRemove
+     * if so, returns an array with matched elements, otherwise returns an empty array
+     *
+     * @param {Node} contextNode - document node from XML document
+     * @returns {Array}
+     */
+    const getXPathElements = (contextNode) => {
         const result = [];
         try {
             const elementsToRemove = propsToRemove.slice(XPATH_MARKER.length, -1);
@@ -116,7 +127,7 @@ export function xmlPrune(source, propsToRemove, optionalProp = '', urlToMatch =
                 result.push(xpathResult.snapshotItem(i));
             }
         } catch (ex) {
-            const message = `Invalid XPath element: ${ex}`;
+            const message = `Invalid XPath parameter: ${propsToRemove}\n${ex}`;
             logMessage(source, message);
         }
         return result;
@@ -160,7 +171,7 @@ export function xmlPrune(source, propsToRemove, optionalProp = '', urlToMatch =
             return false;
         }
         const docXML = createXMLDocument(response);
-        return isXpath ? !!xPathElements(docXML) : !!docXML.querySelector(propsToRemove);
+        return isXpath ? getXPathElements(docXML) : !!docXML.querySelector(propsToRemove);
     };
 
     const pruneXML = (text) => {
@@ -178,7 +189,7 @@ export function xmlPrune(source, propsToRemove, optionalProp = '', urlToMatch =
             return text;
         }
         if (isXpath) {
-            const elements = xPathElements(xmlDoc);
+            const elements = getXPathElements(xmlDoc);
             if (!elements.length) {
                 shouldPruneResponse = false;
                 return text;