gscraper 0.2.4 → 0.3.0

data/lib/gscraper/licenses.rb

@@ -1,5 +1,4 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
@@ -17,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 module GScraper

data/lib/gscraper/page.rb

@@ -1,5 +1,4 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
@@ -17,47 +16,77 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
+require 'enumerator'
+
 module GScraper
   class Page < Array
 
     #
-    # Creates a new Page object with the given _elements_. If a _block_
-    # is given, it will be passed the newly created Page object.
+    # Creates a new Page object.
+    #
+    # @param [Array] elements
+    #   The elements to populate the page with.
+    #
+    # @yield [page]
+    #   If a block is given, it will be passed the newly created page.
+    #
+    # @yieldparam [Page] page
+    #   The newly created page.
     #
-    def initialize(elements=[],&block)
+    def initialize(elements=[])
       super(elements)
 
-      block.call(self) if block
+      yield self if block_given?
     end
 
     #
-    # Returns a mapped Array of the elements within the Page using the
-    # given _block_. If the _block_ is not given, the page will be
-    # returned.
+    # Maps the elements within the page.
     #
-    #   page.map # => Page
+    # @yield [element]
+    #   The given block will be passed each element in the page.
     #
-    #   page.map { |element| element.field } # => [...]
+    # @return [Array, Enumerator]
+    #   The mapped result. If no block was given, an Enumerator object will
+    #   be returned.
     #
-    def map(&block)
-      return self unless block
+    # @example
+    #   page.map
+    #   # => Page
+    #
+    # @example
+    #   page.map { |element| element.field }
+    #   # => [...]
+    #
+    def map
+      return enum_for(:map) unless block_given?
 
       mapped = []
 
-      each { |element| mapped << block.call(element) }
+      each { |element| mapped << yield(element) }
       return mapped
     end
 
     #
-    # Selects the elements within the Page which match the given _block_.
+    # Selects the elements within the page.
+    #
+    # @yield [element]
+    #   The given block will be passed each element in the page.
+    #
+    # @return [Array, Enumerator]
+    #   The selected elements. If no block was given, an Enumerator object
+    #   is returned.
     #
+    # @example
     #   page.select { |element| element.field =~ /ruby/i }
     #
     def select(&block)
-      self.class.new(super(&block))
+      unless block
+        enum_for(:select)
+      else
+        self.class.new(super(&block))
+      end
     end
 
   end

data/lib/gscraper/search.rb

@@ -1,5 +1,4 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
@@ -17,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'gscraper/search/web_query'

data/lib/gscraper/search/ajax_query.rb

@@ -1,5 +1,4 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
@@ -17,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'gscraper/search/result'
@@ -32,6 +30,9 @@ require 'nokogiri'
 
 module GScraper
   module Search
+    #
+    # Represents a Query through the Google AJAX search API.
+    #
     class AJAXQuery < Query
 
       include HasPages
@@ -70,16 +71,28 @@ module GScraper
       attr_accessor :version
 
       #
-      # Creates a new AJAXQuery with the given _options_. If a _block_ is
-      # given it will be passed the newly created AJAXQuery object.
+      # Creates a new AJAX query.
       #
-      # _options_ may contain the following keys:
-      # <tt>:language</tt>:: The search language. Defaults to <tt>:en</tt>.
-      # <tt>:sig</tt>:: The search signature. Defaults to
-      #                 +582c1116317355adf613a6a843f19ece+.
-      # <tt>:key</tt>:: The search key. Defaults to <tt>:notsupplied</tt>.
-      # <tt>:version</tt>:: The desired API version. Defaults to
-      #                     <tt>1.0</tt>.
+      # @param [Hash] options
+      #   Query options.
+      #
+      # @option options [Symbol] :language (:en)
+      #   The search language.
+      #
+      # @option options [String] :sig ('582c1116317355adf613a6a843f19ece')
+      #   The search signature.
+      #
+      # @option options [Symbol] :key (:notsupplied)
+      #   The search key.
+      #
+      # @option options [Float] :version (1.0)
+      #   The desired API version.
+      #
+      # @yield [query]
+      #   If a block is given, the new AJAX query will be passed to it.
+      #
+      # @yieldparam [AJAXQuery] query
+      #   The new AJAX query.
       #
       def initialize(options={},&block)
         @agent = GScraper.web_agent(options)
@@ -94,10 +107,26 @@ module GScraper
       end
 
       #
-      # Creates a new AJAXQuery object from the specified URL. If a block is
-      # given, it will be passed the newly created AJAXQuery object.
+      # Creates a new AJAX query from the specified URL.
+      #
+      # @param [URI::HTTP, String] url
+      #   The URL to create the query from.
+      #
+      # @param [Hash] options
+      #   Additional query options.
+      #
+      # @yield [query]
+      #   If a block is given, it will be passed the new AJAX query.
+      #
+      # @yieldparam [AJAXQuery] query
+      #   The new AJAX query.
+      #
+      # @return [AJAXQuery]
+      #   The new AJAX query.
       #
-      def self.from_url(url,options={},&block)
+      # @see AJAXQuery.new
+      #
+      def AJAXQuery.from_url(url,options={},&block)
         url = URI(url.to_s)
 
         options[:language] = url.query_params['hl']
@@ -111,14 +140,22 @@ module GScraper
       end
 
       #
-      # Returns +RESULTS_PER_PAGE+.
+      # The results per page.
+      #
+      # @return [Integer]
+      #   The number of results per page.
+      #
+      # @see RESULTS_PER_PAGE
       #
       def results_per_page
         RESULTS_PER_PAGE
       end
 
       #
-      # Returns the URL that represents the query.
+      # The URL that represents the query.
+      #
+      # @return [URI::HTTP]
+      #   The URL for the query.
       #
       def search_url
         search_url = URI(API_URL)
@@ -134,8 +171,13 @@ module GScraper
       end
 
       #
-      # Returns the URL that represents the query of a specific
-      # _page_index_.
+      # The URL that represents the query at a specific page index.
+      #
+      # @param [Integer] page_index
+      #   The page index to create the URL for.
+      #
+      # @return [URI::HTTP]
+      #   The query URL for the given page index.
       #
       def page_url(page_index)
         url = search_url
@@ -148,8 +190,13 @@ module GScraper
       end
 
       #
-      # Returns a Page object containing Result objects at the specified
-      # _page_index_.
+      # A page containing results at the specified page index.
+      #
+      # @param [Integer] page_index
+      #   The index of the page.
+      #
+      # @return [Page<Result>]
+      #   A page object.
       #
       def page(page_index)
         Page.new do |new_page|
@@ -162,8 +209,14 @@ module GScraper
             hash['results'].each_with_index do |result,index|
               rank = rank_offset + (index + 1)
               title = Nokogiri::HTML(result['title']).inner_text
-              url = URI(result['unescapedUrl'])
-              summary = Nokogiri::HTML(result['content']).inner_text
+              url = URI(URI.escape(result['unescapedUrl']))
+
+              unless result['content'].empty?
+                summary = Nokogiri::HTML(result['content']).inner_text
+              else
+                summary = ''
+              end
+
               cached_url = URI(result['cacheUrl'])
 
               new_page << Result.new(rank,title,url,summary,cached_url)

data/lib/gscraper/search/page.rb

@@ -1,5 +1,4 @@
 #
-#--
 # GScraper - A web-scraping interface to various Google Services.
 #
 # Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
@@ -17,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'gscraper/search/result'
@@ -27,224 +25,376 @@ module GScraper
   module Search
     class Page < GScraper::Page
 
+      alias results_with select
+
       #
-      # Selects the results using the specified _block_.
+      # Selects the results with the matching title.
       #
-      #   page.results_with { |result| result.title =~ /blog/ }
+      # @param [String, Regexp] title
+      #   The title to search for.
       #
-      def results_with(&block)
-        select(&block)
-      end
-
+      # @yield [result]
+      #   The given block will be passed each matching result.
       #
-      # Selects the results with the matching _title_. The _title_ may be
-      # either a String or a Regexp. If _block_ is given, each matching
-      # result will be passed to the _block_.
+      # @yieldparam [Result] result
+      #   A result with the matching title.
       #
+      # @return [Array<Result>]
+      #   The results with the matching title.
+      #
+      # @example
       #   page.results_with_title('hackety org') #=> Page
       #
+      # @example
       #   page.results_with_title(/awesome/) do |result|
       #     puts result.url
       #   end
       #
-      def results_with_title(title,&block)
-        if title.kind_of?(Regexp)
-          results = results_with { |result| result.title =~ title }
+      def results_with_title(title)
+        unless block_given?
+          enum_for(:results_with_title,title)
         else
-          results = results_with { |result| result.title == title }
-        end
+          results_with do |result|
+            if result.title.match(title)
+              yield result
 
-        results.each(&block) if block
-        return results
+              true
+            end
+          end
+        end
       end
 
       #
-      # Selects the results with the matching _url_. The _url_ may be
-      # either a String or a Regexp. If _block_ is given, each matching
-      # result will be passed to the _block_.
+      # Selects the results with the matching URL.
       #
+      # @param [String, Regexp] url
+      #   The URL to search for.
+      #
+      # @yield [result]
+      #   The given block will be passed each matching result.
+      #
+      # @yieldparam [Result] result
+      #   A result with the matching URL.
+      #
+      # @return [Array<Result>]
+      #   The results with the matching URL.
+      #
+      # @example
       #   page.results_with_url(/\.com/) # => Page
       #
+      # @example
       #   page.results_with_url(/^https:\/\//) do |result|
       #     puts result.title
       #   end
       #
-      def results_with_url(url,&block)
-        if url.kind_of?(Regexp)
-          results = results_with { |result| result.url =~ url }
+      def results_with_url(url)
+        unless block_given?
+          enum_for(:results_with_url,url)
         else
-          results = results_with { |result| result.url == url }
-        end
+          results_with do |result|
+            if result.url.match(url)
+              yield result
 
-        results.each(&block) if block
-        return results
+              true
+            end
+          end
+        end
       end
 
       #
-      # Selects the results with the matching _summary_. The _summary_ may
-      # be either a String or a Regexp. If _block_ is given, each matching
-      # result will be passed to the _block_.
+      # Selects the results with the matching summary.
       #
+      # @param [String, Regexp] summary
+      #   The summary to search for.
+      #
+      # @yield [result]
+      #   The given block will be passed each matching result.
+      #
+      # @yieldparam [Result] result
+      #   A result with the matching summary.
+      #
+      # @return [Array<Result>]
+      #   The results with the matching summary.
+      #
+      # @example
       #   page.results_with_summary(/cheese cake/) # => Page
       #
+      # @example
       #   page.results_with_summary(/Scientifically/) do |result|
       #     puts result.url
       #   end
       #
-      def results_with_summary(summary,&block)
-        if summary.kind_of?(Regexp)
-          results = results_with { |result| result.summary =~ summary }
+      def results_with_summary(summary)
+        unless block_given?
+          enum_for(:results_with_summary,summary)
         else
-          results = results_with { |result| result.summary == summary }
-        end
+          results_with do |result|
+            if result.summary.match(summary)
+              yield result
 
-        results.each(&block) if block
-        return results
+              true
+            end
+          end
+        end
       end
 
       #
-      # Returns an Array containing the ranks of the results within the
-      # Page.
+      # Iterates over each result's rank within the page.
       #
-      #   page.ranks # => [...]
+      # @yield [rank]
+      #   The given block will be passed the ranks of each result in
+      #   the page.
       #
-      def ranks
-        map { |result| result.rank }
+      # @yieldparam [Integer] rank
+      #   The rank of a result in the page.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_rank { |rank| puts rank }
+      #
+      def each_rank
+        unless block_given?
+          enum_for(:each_rank)
+        else
+          each { |result| yield result.rank }
+        end
       end
 
       #
-      # Returns an Array containing the titles of the results within the
-      # Page.
+      # Iterates over each result's title within the page.
       #
-      #   page.titles # => [...]
+      # @yield [title]
+      #   The given block will be passed the title of each result in
+      #   the page.
+      #  
+      # @yieldparam [String] title
+      #   The title of a result in the page.
       #
-      def titles
-        map { |result| result.title }
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_title { |title| puts title }
+      #
+      def each_title
+        unless block_given?
+          enum_for(:each_title)
+        else
+          each { |result| yield result.title }
+        end
       end
 
       #
-      # Returns an Array containing the URLs of the results within the
-      # Page.
+      # Iterates over each result's url within the page.
       #
-      #   page.urls # => [...]
+      # @yield [url]
+      #   The given block will be passed the URL of each result in
+      #   the page.
+      #  
+      # @yieldparam [URI::HTTP] url
+      #   The URL of a result in the page.
       #
-      def urls
-        map { |result| result.url }
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_url { |url| puts url }
+      #
+      def each_url
+        unless block_given?
+          enum_for(:each_url)
+        else
+          each { |result| yield result.url }
+        end
       end
 
       #
-      # Returns an Array containing the summaries of the results within the
-      # Page.
+      # Iterates over each result's summary within the page.
       #
-      #   page.summaries # => [...]
+      # @yield [summary]
+      #   The given block will be passed the summary of each result in
+      #   the page.
+      #  
+      # @yieldparam [String] summary
+      #   The summary of a result in the page.
       #
-      def summaries
-        map { |result| result.summary }
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_summary { |summary| puts summary }
+      #
+      def each_summary
+        unless block_given?
+          enum_for(:each_summary)
+        else
+          each { |result| yield result.summary }
+        end
       end
 
       #
-      # Returns an Array containing the cached URLs of the results within
-      # the Page.
+      # Iterates over each result's cached URLs within the page.
       #
-      #   page.cached_urls # => [...]
+      # @yield [cached_url]
+      #   The given block will be passed the Cached URL of each result in
+      #   the page.
+      #  
+      # @yieldparam [URI::HTTP] cached_url
+      #   The Cached URL of a result in the page.
       #
-      def cached_urls
-        map { |result| result.cached_url }.compact
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_cached_url { |cached_url| puts cached_url }
+      #
+      def each_cached_url
+        unless block_given?
+          enum_for(:each_cached_url)
+        else
+          each do |result|
+            yield result.cached_url if result.cached_url
+          end
+        end
       end
 
       #
-      # Returns an Array containing the cached pages of the results within
-      # the Page.
+      # Iterates over each result's cached pages within the page.
       #
-      #   page.cached_pages # => [...]
+      # @yield [cached_page]
+      #   The given block will be passed the Cached Page of each result in
+      #   the page.
+      #  
+      # @yieldparam [Mechanize::Page] cached_page
+      #   The Cached Page of a result in the page.
       #
-      def cached_pages
-        map { |result| result.cached_page }.compact
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_cached_page { |page| puts page.readlines }
+      #
+      def each_cached_page
+        unless block_given?
+          enum_for(:each_cached_page)
+        else
+          each do |result|
+            yield result.cached_page if result.cached_page
+          end
+        end
       end
 
       #
-      # Returns an Array containing the similar Query URLs of the results
-      # within the Page.
+      # Iterates over each result's similar Query URLs within the page.
       #
-      #   page.similar_urls # => [...]
+      # @yield [similar_url]
+      #   The given block will be passed the Similar Query URL of each
+      #   result in the page.
+      #  
+      # @yieldparam [URI::HTTP] similar_url
+      #   The Cached URL of a result in the page.
       #
-      def similar_urls
-        map { |result| result.similar_url }.compact
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator object will be returned.
+      #
+      # @example
+      #   each_similar_url { |similar_url| puts similar_url }
+      #
+      def each_similar_url
+        unless block_given?
+          enum_for(:each_similar_url)
+        else
+          each do |result|
+            yield result.similar_url if result.similar_url
+          end
+        end
       end
 
       #
-      # Iterates over each result's rank within the Page, passing each to
-      # the given _block_.
+      # Returns the ranks of the results in the page.
       #
-      #   each_rank { |rank| puts rank }
+      # @return [Array<Integer>]
+      #   The ranks of the results.
       #
-      def each_rank(&block)
-        ranks.each(&block)
+      def ranks
+        each_rank.to_a
       end
 
       #
-      # Iterates over each result's title within the Page, passing each to
-      # the given _block_.
+      # Returns the titles of the results in the page.
       #
-      #   each_title { |title| puts title }
+      # @return [Array<String>]
+      #   The titles of the results.
       #
-      def each_title(&block)
-        titles.each(&block)
+      def titles
+        each_title.to_a
       end
 
       #
-      # Iterates over each result's url within the Page, passing each to
-      # the given _block_.
+      # Returns the URLs of the results in the page.
       #
-      #   each_url { |url| puts url }
+      # @return [Array<URI::HTTP>]
+      #   The URLs of the results.
       #
-      def each_url(&block)
-        urls.each(&block)
+      def urls
+        each_url.to_a
       end
 
       #
-      # Iterates over each result's summary within the Page, passing each
-      # to the given _block_.
+      # Returns the summaries of the results in the page.
       #
-      #   each_summary { |summary| puts summary }
+      # @return [Array<String>]
+      #   The summaries of the results.
       #
-      def each_summary(&block)
-        summaries.each(&block)
+      def summaries
+        each_summary.to_a
       end
 
       #
-      # Iterates over each result's cached URLs within the Page, passing
-      # each to the given _block_.
+      # Returns the Cached URLs of the results in the page.
       #
-      #   each_cached_url { |url| puts url }
+      # @return [Array<URI::HTTP>]
+      #   The Cached URLs of the results.
       #
-      def each_cached_url(&block)
-        cached_urls.each(&block)
+      def cached_urls
+        each_cached_url.to_a
       end
 
       #
-      # Iterates over each result's cached pages within the Page, passing
-      # each to the given _block_.
+      # Returns the Cached Pages of the results in the page.
       #
-      #   each_cached_page { |page| puts page.readlines }
+      # @return [Array<Mechanize::Page>]
+      #   The Cached Pages of the results.
       #
-      def each_cached_page(&block)
-        cached_pages.each(&block)
+      def cached_pages
+        each_cached_page.to_a
       end
 
       #
-      # Iterates over each result's similar Query URLs within the Page,
-      # passing each to the given _block_.
+      # Returns the Similar Query URLs of the results in the page.
       #
-      #   each_similar_url { |url| puts url }
+      # @return [Array<URI::HTTP>]
+      #   The Similar Query URLs of the results.
       #
-      def each_similar_url(&block)
-        similar_urls.each(&block)
+      def similar_urls
+        each_similar_url.to_a
       end
 
       #
-      # Returns the ranks of the results that match the specified _block_.
+      # Returns the ranks of the results that match the given block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
       #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<Integer>]
+      #   The ranks of the results which match the given block.
+      #
+      # @example
       #   page.ranks_of { |result| result.title =~ /awesome/ }
       #
       def ranks_of(&block)
@@ -252,8 +402,18 @@ module GScraper
       end
 
       #
-      # Returns the titles of the results that match the specified _block_.
+      # Returns the titles of the results that match the given block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
       #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<String>]
+      #   The titles of the results which match the given block.
+      #
+      # @example
       #   page.titles_of { |result| result.url.include?('www') }
       #
       def titles_of(&block)
@@ -261,8 +421,18 @@ module GScraper
       end
 
       #
-      # Returns the urls of the results that match the specified _block_.
+      # Returns the urls of the results that match the given block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
       #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<URI::HTTP>]
+      #   The URLs of the results which match the given block.
+      #
+      # @example
       #   page.urls_of { |result| result.summary =~ /awesome pants/ }
       #
       def urls_of(&block)
@@ -270,9 +440,18 @@ module GScraper
       end
 
       #
-      # Returns the summaries of the results that match the specified
-      # _block_.
+      # Returns the summaries of the results that match the given block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
       #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<String>]
+      #   The summaries of the results which match the given block.
+      #
+      # @example
       #   page.summaries_of { |result| result.title =~ /what if/ }
       #
       def summaries_of(&block)
@@ -280,9 +459,18 @@ module GScraper
       end
 
       #
-      # Returns the cached URLs of the results that match the specified
-      # _block_.
+      # Returns the Cached URLs of the results that match the given block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
       #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<URI::HTTP>]
+      #   The Cached URLs of the results which match the given block.
+      #
+      # @example
       #   page.cached_urls_of { |result| result.title =~ /howdy/ }
       #
       def cached_urls_of(&block)
@@ -290,20 +478,38 @@ module GScraper
       end
 
       #
-      # Returns the cached pages of the results that match the specified
-      # _block_. If _options_ are given, they will be used in accessing
-      # the cached pages.
+      # Returns the cached pages of the results that match the given block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
       #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<Mechanize::Page>]
+      #   The Cached Page of the results which match the given block.
+      #
+      # @example
       #   page.cached_pages_of { |result| result.title =~ /dude/ }
       #
-      def cached_pages_of(options={},&block)
-        results_with(&block).cached_pages(options)
+      def cached_pages_of(&block)
+        results_with(&block).cached_pages
       end
 
       #
-      # Returns the similar query URLs of the results that match the
-      # specified _block_.
+      # Returns the Similar Query URLs of the results that match the given
+      # block.
+      #
+      # @yield [result]
+      #   The given block will be used to filter the results in the page.
+      #
+      # @yieldparam [Result] result
+      #   A result in the page.
+      #
+      # @return [Array<URI::HTTP>]
+      #   The Similar Query URLs of the results which match the given block.
       #
+      # @example
       #   page.similar_urls_of { |result| result.title =~ /what if/ }
       #
       def similar_urls_of(&block)