diff --git a/lib/oga/xml/querying.rb b/lib/oga/xml/querying.rb
index 43a4d31..d834d61 100644
--- a/lib/oga/xml/querying.rb
+++ b/lib/oga/xml/querying.rb
@@ -8,8 +8,32 @@ module Oga
##
# Evaluates the given XPath expression.
#
+ # Querying a document:
+ #
+ # document = Oga.parse_xml <<-EOF
+ #
+ # Alice
+ #
+ # EOF
+ #
+ # document.xpath('people/person')
+ #
+ # Querying an element:
+ #
+ # element = document.at_xpath('people')
+ #
+ # element.xpath('person')
+ #
+ # Using variable bindings:
+ #
+ # document.xpath('people/person[@age = $age]', 'age' => 25)
+ #
# @param [String] expression The XPath expression to run.
- # @param [Hash] variables Variables to bind.
+ #
+ # @param [Hash] variables Variables to bind. The keys of this Hash should
+ # be String values.
+ #
+ # @return [Oga::XML::NodeSet]
#
def xpath(expression, variables = {})
ast = XPath::Parser.parse_with_cache(expression)
@@ -19,10 +43,22 @@ module Oga
end
##
- # Evaluates the given XPath expression and returns the first node in the
- # set.
+ # Evaluates the XPath expression and returns the first matched node.
+ #
+ # Querying a document:
+ #
+ # document = Oga.parse_xml <<-EOF
+ #
+ # Alice
+ #
+ # EOF
+ #
+ # person = document.at_xpath('people/person')
+ #
+ # person.class # => Oga::XML::Element
#
# @see [#xpath]
+ # @return [Oga::XML::Node|Oga::XML::Attribute]
#
def at_xpath(*args)
result = xpath(*args)
@@ -33,7 +69,18 @@ module Oga
##
# Evaluates the given CSS expression.
#
+ # Querying a document:
+ #
+ # document = Oga.parse_xml <<-EOF
+ #
+ # Alice
+ #
+ # EOF
+ #
+ # document.css('people person')
+ #
# @param [String] expression The CSS expression to run.
+ # @return [Oga::XML::NodeSet]
#
def css(expression)
ast = CSS::Parser.parse_with_cache(expression)
@@ -43,10 +90,10 @@ module Oga
end
##
- # Evaluates the given CSS expression and returns the first node in the
- # set.
+ # Evaluates the CSS expression and returns the first matched node.
#
# @see [#css]
+ # @return [Oga::XML::Node|Oga::XML::Attribute]
#
def at_css(*args)
result = css(*args)