Tweaked docs of the XPath code a bit.

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

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;

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