Improve documentation

heyvito · heyvito · commit eac191f76559 · 2020-10-01T09:47:36.000-03:00
diff --git a/README.md b/README.md
@@ -8,9 +8,12 @@ xmlquery
 Overview
 ===
 
-`xmlquery` is an XPath query package for XML document, lets you extract data or evaluate from XML documents by an XPath expression.
+`xmlquery` is an XPath query package for XML documents, allowing you to extract 
+data or evaluate from XML documents with an XPath expression.
 
-`xmlquery` built-in the query object caching feature will caching the recently used XPATH query string. Enable caching can avoid re-compile XPath expression each query. 
+`xmlquery` has a built-in query object caching feature that caches recently used
+XPATH query strings. Enabling caching can avoid recompile XPath expression for 
+each query. 
 
 Change Logs
 ===
@@ -22,16 +25,16 @@ Change Logs
 - Add XPath query caching.
 
 2019-10-05 
-- Add new methods that compatible with invalid XPath expression error: `QueryAll` and `Query`.
-- Add `QuerySelector` and `QuerySelectorAll` methods, supported reused your query object.
+- Add new methods compatible with invalid XPath expression error: `QueryAll` and `Query`.
+- Add `QuerySelector` and `QuerySelectorAll` methods, support for reused query objects.
 - PR [#12](https://github.com/antchfx/xmlquery/pull/12) (Thanks @FrancescoIlario)
 - PR [#11](https://github.com/antchfx/xmlquery/pull/11) (Thanks @gjvnq)
 
 2018-12-23
-- added XML output will including comment node. [#9](https://github.com/antchfx/xmlquery/issues/9)
+- Added XML output including comment nodes. [#9](https://github.com/antchfx/xmlquery/issues/9)
 
 2018-12-03
-- added support attribute name with namespace prefix and XML output. [#6](https://github.com/antchfx/xmlquery/issues/6)
+- Added support to attribute name with namespace prefix and XML output. [#6](https://github.com/antchfx/xmlquery/issues/6)
 
 Installation
 ====
@@ -71,7 +74,7 @@ f, err := os.Open("../books.xml")
 doc, err := xmlquery.Parse(f)
 ```
 
-#### Parse an XML in a stream fashion (simple case without element filtering).
+#### Parse an XML in a stream fashion (simple case without elements filtering).
 
 ```go
 f, err := os.Open("../books.xml")
@@ -117,33 +120,33 @@ list := xmlquery.Find(doc, "//author")
 book := xmlquery.FindOne(doc, "//book[2]")
 ```
 
-#### Find all book elements and only get `id` attribute self. (New Feature)
+#### Find all book elements and only get `id` attribute. (New Feature)
 
 ```go
 list := xmlquery.Find(doc,"//book/@id")
 ```
 
-#### Find all books with id is bk104.
+#### Find all books with id `bk104`.
 
 ```go
 list := xmlquery.Find(doc, "//book[@id='bk104']")
 ```
 
-#### Find all books that price less than 5.
+#### Find all books with price less than 5.
 
 ```go
 list := xmlquery.Find(doc, "//book[price<5]")
 ```
 
-#### Evaluate the total price of all books.
+#### Evaluate total price of all books.
 
 ```go
 expr, err := xpath.Compile("sum(//book/price)")
 price := expr.Evaluate(xmlquery.CreateXPathNavigator(doc)).(float64)
 fmt.Printf("total price: %f\n", price)
 ```
 
-#### Evaluate the number of all books element.
+#### Evaluate number of all book elements.
 
 ```go
 expr, err := xpath.Compile("count(//book)")
@@ -155,14 +158,17 @@ FAQ
 
 #### `Find()` vs `QueryAll()`, which is better?
 
-`Find` and `QueryAll` both do the same things, searches all of matched html nodes.
-The `Find` will panics if you give an error XPath query, but `QueryAll` will return an error for you.
+`Find` and `QueryAll` both do the same thing: searches all of matched XML nodes.
+`Find` panics if provided with an invalid XPath query, while `QueryAll` returns
+an error.
 
 #### Can I save my query expression object for the next query?
 
-Yes, you can. We offer the `QuerySelector` and `QuerySelectorAll` methods, It will accept your query expression object.
+Yes, you can. We provide `QuerySelector` and `QuerySelectorAll` methods; they 
+accept your query expression object.
 
-Cache a query expression object(or reused) will avoid re-compile XPath query expression, improve your query performance.
+Caching a query expression object avoids recompiling the XPath query 
+expression, improving query performance.
 
 #### Create XML document.
 
@@ -247,9 +253,9 @@ List of supported XPath query packages
 ===
 | Name                                              | Description                               |
 | ------------------------------------------------- | ----------------------------------------- |
-| [htmlquery](https://github.com/antchfx/htmlquery) | XPath query package for the HTML document |
-| [xmlquery](https://github.com/antchfx/xmlquery)   | XPath query package for the XML document  |
-| [jsonquery](https://github.com/antchfx/jsonquery) | XPath query package for the JSON document |
+| [htmlquery](https://github.com/antchfx/htmlquery) | XPath query package for HTML documents    |
+| [xmlquery](https://github.com/antchfx/xmlquery)   | XPath query package for XML documents     |
+| [jsonquery](https://github.com/antchfx/jsonquery) | XPath query package for JSON documents    |
 
  Questions
 ===
diff --git a/node.go b/node.go
@@ -14,8 +14,8 @@ const (
 	// DocumentNode is a document object that, as the root of the document tree,
 	// provides access to the entire XML document.
 	DocumentNode NodeType = iota
-	// DeclarationNode is the document type declaration, indicated by the following
-	// tag (for example, <!DOCTYPE...> ).
+	// DeclarationNode is the document type declaration, indicated by the
+	// following tag (for example, <!DOCTYPE...> ).
 	DeclarationNode
 	// ElementNode is an element (for example, <item> ).
 	ElementNode
diff --git a/parse.go b/parse.go
@@ -117,7 +117,7 @@ func (p *parser) parse() (*Node, error) {
 				Attr:         tok.Attr,
 				level:        p.level,
 			}
-			//fmt.Println(fmt.Sprintf("start > %s : %d", node.Data, node.level))
+
 			if p.level == p.prev.level {
 				AddSibling(p.prev, node)
 			} else if p.level > p.prev.level {
@@ -227,13 +227,16 @@ func (p *parser) parse() (*Node, error) {
 	}
 }
 
-// StreamParser enables loading and parsing an XML document in a streaming fashion.
+// StreamParser enables loading and parsing an XML document in a streaming
+// fashion.
 type StreamParser struct {
 	p *parser
 }
 
-// CreateStreamParser creates a StreamParser. Argument streamElementXPath is required.
-// Argument streamElementFilter is optional and should only be used in advanced scenarios.
+// CreateStreamParser creates a StreamParser. Argument streamElementXPath is
+// required.
+// Argument streamElementFilter is optional and should only be used in advanced
+// scenarios.
 //
 // Scenario 1: simple case:
 //  xml := `<AAA><BBB>b1</BBB><BBB>b2</BBB></AAA>`
@@ -268,12 +271,15 @@ type StreamParser struct {
 // Output will be:
 //   <BBB>b2</BBB>
 //
-// As the argument names indicate, streamElementXPath should be used for providing xpath query pointing
-// to the target element node only, no extra filtering on the element itself or its children; while
-// streamElementFilter, if needed, can provide additional filtering on the target element and its children.
+// As the argument names indicate, streamElementXPath should be used for
+// providing xpath query pointing to the target element node only, no extra
+// filtering on the element itself or its children; while streamElementFilter,
+// if needed, can provide additional filtering on the target element and its
+// children.
 //
-// CreateStreamParser returns error if either streamElementXPath or streamElementFilter, if provided, cannot
-// be successfully parsed and compiled into a valid xpath query.
+// CreateStreamParser returns an error if either streamElementXPath or
+// streamElementFilter, if provided, cannot be successfully parsed and compiled
+// into a valid xpath query.
 func CreateStreamParser(r io.Reader, streamElementXPath string, streamElementFilter ...string) (*StreamParser, error) {
 	elemXPath, err := getQuery(streamElementXPath)
 	if err != nil {
@@ -294,12 +300,13 @@ func CreateStreamParser(r io.Reader, streamElementXPath string, streamElementFil
 	return sp, nil
 }
 
-// Read returns a target node that satisifies the XPath specified by caller at StreamParser creation
-// time. If there is no more satisifying target node after reading the rest of the XML document, io.EOF
-// will be returned. At any time, any XML parsing error encountered, the error will be returned and
-// the stream parsing is stopped. Calling Read() after an error is returned (including io.EOF) is not
-// allowed the behavior will be undefined. Also note, due to the streaming nature, calling Read() will
-// automatically remove any previous target node(s) from the document tree.
+// Read returns a target node that satisfies the XPath specified by caller at
+// StreamParser creation time. If there is no more satisfying target nodes after
+// reading the rest of the XML document, io.EOF will be returned. At any time,
+// any XML parsing error encountered will be returned, and the stream parsing
+// stopped. Calling Read() after an error is returned (including io.EOF) results
+// undefined behavior. Also note, due to the streaming nature, calling Read()
+// will automatically remove any previous target node(s) from the document tree.
 func (sp *StreamParser) Read() (*Node, error) {
 	// Because this is a streaming read, we need to release/remove last
 	// target node from the node tree to free up memory.
diff --git a/query.go b/query.go
@@ -44,7 +44,8 @@ func (n *Node) SelectAttr(name string) string {
 
 var _ xpath.NodeNavigator = &NodeNavigator{}
 
-// CreateXPathNavigator creates a new xpath.NodeNavigator for the specified html.Node.
+// CreateXPathNavigator creates a new xpath.NodeNavigator for the specified
+// XML Node.
 func CreateXPathNavigator(top *Node) *NodeNavigator {
 	return &NodeNavigator{curr: top, root: top, attr: -1}
 }
@@ -67,8 +68,8 @@ func getCurrentNode(it *xpath.NodeIterator) *Node {
 	return n.curr
 }
 
-// Find is like QueryAll but it will panics if the `expr` is not a
-// valid XPath expression. See `QueryAll()` function.
+// Find is like QueryAll but panics if `expr` is not a valid XPath expression.
+// See `QueryAll()` function.
 func Find(top *Node, expr string) []*Node {
 	nodes, err := QueryAll(top, expr)
 	if err != nil {
@@ -77,8 +78,8 @@ func Find(top *Node, expr string) []*Node {
 	return nodes
 }
 
-// FindOne is like Query but it will panics if the `expr` is not a
-// valid XPath expression. See `Query()` function.
+// FindOne is like Query but panics if `expr` is not a valid XPath expression.
+// See `Query()` function.
 func FindOne(top *Node, expr string) *Node {
 	node, err := Query(top, expr)
 	if err != nil {
@@ -88,7 +89,7 @@ func FindOne(top *Node, expr string) *Node {
 }
 
 // QueryAll searches the XML Node that matches by the specified XPath expr.
-// Return an error if the expression `expr` cannot be parsed.
+// Returns an error if the expression `expr` cannot be parsed.
 func QueryAll(top *Node, expr string) ([]*Node, error) {
 	exp, err := getQuery(expr)
 	if err != nil {
@@ -98,7 +99,7 @@ func QueryAll(top *Node, expr string) ([]*Node, error) {
 }
 
 // Query searches the XML Node that matches by the specified XPath expr,
-// and returns first element of matched.
+// and returns first matched element.
 func Query(top *Node, expr string) (*Node, error) {
 	exp, err := getQuery(expr)
 	if err != nil {
@@ -107,7 +108,8 @@ func Query(top *Node, expr string) (*Node, error) {
 	return QuerySelector(top, exp), nil
 }
 
-// QuerySelectorAll searches all of the XML Node that matches the specified XPath selectors.
+// QuerySelectorAll searches all of the XML Node that matches the specified
+// XPath selectors.
 func QuerySelectorAll(top *Node, selector *xpath.Expr) []*Node {
 	t := selector.Select(CreateXPathNavigator(top))
 	var elems []*Node
@@ -117,7 +119,8 @@ func QuerySelectorAll(top *Node, selector *xpath.Expr) []*Node {
 	return elems
 }
 
-// QuerySelector returns the first matched XML Node by the specified XPath selector.
+// QuerySelector returns the first matched XML Node by the specified XPath
+// selector.
 func QuerySelector(top *Node, selector *xpath.Expr) *Node {
 	t := selector.Select(CreateXPathNavigator(top))
 	if t.MoveNext() {
@@ -127,16 +130,16 @@ func QuerySelector(top *Node, selector *xpath.Expr) *Node {
 }
 
 // FindEach searches the html.Node and calls functions cb.
-// Important: this method has deprecated, recommend use for .. = range Find(){}.
+// Important: this method is deprecated, instead, use for .. = range Find(){}.
 func FindEach(top *Node, expr string, cb func(int, *Node)) {
 	for i, n := range Find(top, expr) {
 		cb(i, n)
 	}
 }
 
-// FindEachWithBreak functions the same as FindEach but allows you
-// to break the loop by returning false from your callback function, cb.
-// Important: this method has deprecated, recommend use for .. = range Find(){}.
+// FindEachWithBreak functions the same as FindEach but allows to break the loop
+// by returning false from the callback function `cb`.
+// Important: this method is deprecated, instead, use .. = range Find(){}.
 func FindEachWithBreak(top *Node, expr string, cb func(int, *Node) bool) {
 	for i, n := range Find(top, expr) {
 		if !cb(i, n) {
