Add comments for XmlProvider and xml_root_path opt

config/xmldp.go

@@ -34,11 +34,21 @@ func NewXmlProvider(req *xmlquery.Node, cdrPath utils.HierarchyPath) (dP utils.D
 	return
 }
 
-// XmlProvider implements engine.utils.DataProvider so we can pass it to filters
+// XmlProvider implements engine.utils.DataProvider, allowing it to be passed to filters.
+// An instance of XmlProvider is created for each element retrieved from xmlquery.QueryAll.
 type XmlProvider struct {
-	req     *xmlquery.Node
-	cdrPath utils.HierarchyPath //used to compute relative path
-	cache   utils.MapStorage
+
+	// req is the root node of each individual XML element retrieved.
+	// It acts as the starting point for extracting data from the XML element.
+	req *xmlquery.Node
+
+	// cdrPath is the root path used to calculate the relative path.
+	// The relative path is computed by trimming cdrPath from the full path of the XML element.
+	cdrPath utils.HierarchyPath
+
+	// cache stores the inner text of XML elements.
+	// The key is the relative path of the XML element.
+	cache utils.MapStorage
 }
 
 // String is part of engine.utils.DataProvider interface

ers/filexml.go

@@ -114,6 +114,28 @@ func (rdr *XMLFileER) Serve() (err error) {
 	return
 }
 
+/*
+   `xml_root_path` is a slice that determines the which XML nodes to process.
+   When used by `xmlquery.QueryAll()`, it behaves as follows:
+
+   ```xml
+   <?xml version="1.0" encoding="ISO-8859-1"?>
+   <A>
+       <B>
+           <C>item1</C>
+           <D>item2</D>
+       </B>
+       <B>
+           <C>item3</C>
+       </B>
+   </A>
+   ```
+
+   - If the root_path_string is empty or ["A"], it retrieves everything within <A></A>.
+   - For ["A", "B"], it retrieves each <B></B> element.
+   - For ["A", "B", "C"], it retrieves the text within each <C></C> ("item1" and "item3").
+*/
+
 // processFile is called for each file in a directory and dispatches erEvents from it
 func (rdr *XMLFileER) processFile(fPath, fName string) error {
 	if cap(rdr.conReqs) != 0 { // 0 goes for no limit