From 1fdf876a93695ae5432e960d3c137ba9a084e976 Mon Sep 17 00:00:00 2001
From: Yorick Peterse <yorickpeterse@gmail.com>
Date: Thu, 4 Sep 2014 10:17:32 +0200
Subject: [PATCH] Tweaked docs of the XPath code a bit.

---
 lib/oga/xpath/evaluator.rb |  8 ++++----
 lib/oga/xpath/lexer.rl     | 29 ++++++++++++++++++++++++++++-
 lib/oga/xpath/parser.y     |  3 ++-
 3 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/lib/oga/xpath/evaluator.rb b/lib/oga/xpath/evaluator.rb
index de43045..7508791 100644
--- a/lib/oga/xpath/evaluator.rb
+++ b/lib/oga/xpath/evaluator.rb
@@ -105,6 +105,7 @@ module Oga
       # the node type.
       #
       # @param [Oga::XPath::Node] ast_node The XPath AST node to process.
+      #
       # @param [Oga::XML::NodeSet] context The context (a set of nodes) to
       #  evaluate an expression in.
       #
@@ -161,8 +162,7 @@ module Oga
       end
 
       ##
-      # Processes a node test. Nodes are compared using {#node_matches?} so see
-      # that method for more information on that matching logic.
+      # Processes a node test and optionally a predicate.
       #
       # @param [Oga::XPath::Node] ast_node
       # @param [Oga::XML::NodeSet] context
@@ -295,8 +295,8 @@ module Oga
       end
 
       ##
-      # Evaluates the `child` axis. This simply delegates work to {#on_test}
-      # or {#on_node_type}.
+      # Evaluates the `child` axis. This axis simply takes all the child nodes
+      # of the current context nodes.
       #
       # @param [Oga::XPath::Node] ast_node
       # @param [Oga::XML::NodeSet] context
diff --git a/lib/oga/xpath/lexer.rl b/lib/oga/xpath/lexer.rl
index 998febf..3e30d3c 100644
--- a/lib/oga/xpath/lexer.rl
+++ b/lib/oga/xpath/lexer.rl
@@ -3,7 +3,34 @@
 module Oga
   module XPath
     ##
-    # Ragel lexer for lexing XPath expressions.
+    # Lexer for turning XPath expressions into a set of tokens. Tokens are
+    # returned as arrays with every array having two values:
+    #
+    # 1. The token type as a symbol
+    # 2. The token value or nil if there is no value
+    #
+    # Basic usage of this lexer is as following:
+    #
+    #     lexer  = Oga::XPath::Lexer.new('//foo/bar')
+    #     tokens = lexer.lex
+    #
+    # Alternatively you can stream tokens instead of returning them as a whole:
+    #
+    #     lexer = Oga::XPath::Lexer.new('//foo/bar')
+    #
+    #     lexer.advance do |type, value|
+    #
+    #     end
+    #
+    # Unlike the XML lexer the XPath lexer does not support IO instances, it can
+    # only lex strings.
+    #
+    # ## Thread Safety
+    #
+    # This class keeps track of an internal state. As a result it's not safe to
+    # share a single instance between multiple threads. However, you're free to
+    # use separate instances per thread as there is no global (= class level)
+    # shared state.
     #
     class Lexer
       %% write data;
diff --git a/lib/oga/xpath/parser.y b/lib/oga/xpath/parser.y
index 4c68743..6d1ee3b 100644
--- a/lib/oga/xpath/parser.y
+++ b/lib/oga/xpath/parser.y
@@ -1,5 +1,6 @@
 ##
-# Parser for XPath expressions.
+# AST parser for XPath expressions. The AST is built using {Oga::XPath::Node}
+# instances.
 #
 class Oga::XPath::Parser