sphinx 0.9.10.2043 → 0.9.10.2091

data/.gitignore

@@ -1,2 +1,4 @@
 rdoc
+doc
+.yardoc
 pkg

data/README.rdoc

@@ -1,10 +1,10 @@
-=Sphinx Client API 0.9.10
+= Sphinx Client API 0.9.10
 
-This document gives an overview of what is Sphinx itself and how to use in 
-within Ruby on Rails. For more information or documentation, 
+This document gives an overview of what is Sphinx itself and how to use it 
+from your Ruby on Rails application. For more information or documentation, 
 please go to http://www.sphinxsearch.com
 
-==Sphinx
+== Sphinx
 
 Sphinx is a standalone full-text search engine, meant to provide fast, 
 size-efficient and relevant fulltext search functions to other applications. 
@@ -12,37 +12,191 @@ Sphinx was specially designed to integrate well with SQL databases and
 scripting languages. Currently built-in data sources support fetching data 
 either via direct connection to MySQL, or from an XML pipe.
  
-Simplest way to communicate with Sphinx is to use <tt>searchd</tt> -
-a daemon to search through fulltext indices from external software.
+Simplest way to communicate with Sphinx is to use <tt>searchd</tt> —
+a daemon to search through full text indexes from external software.
 
-==Compatibility
+== Installation
 
-This version supports all API features of Sphinx 0.9.10-r2043. Full compatibility list:
+There are two options when approaching sphinx plugin installation:
 
-* <tt>0.9.10</tt> — Sphinx 0.9.10-r2043
-* <tt>0.9.9</tt> — Sphinx 0.9.9-r1299
+* using the gem (recommended)
+* install as a Rails plugin
 
-==Documentation
+To install as a gem, add this to your environment.rb:
 
-You can create the documentation by running:
+  config.gem 'sphinx', :source => 'http://gemcutter.org'
 
-	rake rdoc
+And then run the command:
 
-==Latest version
+  sudo rake gems:install
 
-You can always get latest version from
+To install Sphinx as a Rails plugin use this:
+
+  script/plugin install git://github.com/kpumuk/sphinx.git
+
+== Documentation
+
+Complete Sphinx plugin documentation could be found here:
+http://kpumuk.github.com/sphinx
+
+Also you can find documentation on rdoc.info:
+http://rdoc.info/projects/kpumuk/sphinx
+
+You can build the documentation locally by running:
+
+  rake yard
+
+Please note: you should have yard gem installed on your system:
+
+  sudo gem install yard --source http://gemcutter.org
+
+Complete Sphinx API documentation could be found on Sphinx Search Engine
+site: http://www.sphinxsearch.com/docs/current.html
+This plugin is fully compatible with original PHP API implementation.
+
+== Ruby naming conventions
+
+Sphinx Client API supports Ruby naming conventions, so every API
+method name is in underscored, lowercase form:
+
+  SetServer    -> set_server
+  RunQueries   -> run_queries
+  SetMatchMode -> set_match_mode
+
+Every method is aliased to a corresponding one from standard Sphinx
+API, so you can use both <tt>SetServer</tt> and <tt>set_server</tt>
+with no differrence.
+
+There are three exceptions to this naming rule:
+
+  GetLastError   -> last_error
+  GetLastWarning -> last_warning
+  IsConnectError -> connect_error?
+
+Of course, all of them are aliased to the original method names.
+
+== Using multiple Sphinx servers
+
+Since we actively use this plugin in our Scribd development workflow,
+there are several methods have been added to accommodate our needs.
+You can find documentation on Ruby-specific methods in documentation:
+http://rdoc.info/projects/kpumuk/sphinx
+
+First of all, we added support of multiple Sphinx servers to balance
+load between them. Also it means that in case of any problems with one
+of servers, library will try to fetch the results from another one.
+Every consequence request will be executed on the next server in list
+(round-robin technique).
+
+  sphinx.set_servers([
+    { :host => 'browse01.local', :port => 3312 },
+    { :host => 'browse02.local', :port => 3312 },
+    { :host => 'browse03.local', :port => 3312 }
+  ])
+
+By default library will try to fetch results from a single server, and
+fail if it does not respond. To setup number of retries being performed,
+you can use second (additional) parameter of the <tt>set_connect_timeout</tt>
+and <tt>set_request_timeout</tt> methods:
+
+  sphinx.set_connect_timeout(1, 3)
+  sphinx.set_request_timeout(1, 3)
+
+There is a big difference between these two methods. First will affect
+only on requests experiencing problems with connection (socket error,
+pipe error, etc), second will be used when request is broken somehow
+(temporary searchd error, incomplete reply, etc). The workflow looks like
+this:
+
+1. Increase retries number. If is less or equal to configured value,
+   try to connect to the next server. Otherwise, raise an error.
+2. In case of connection problem go to 1.
+3. Increase request retries number. If it less or equal to configured
+   value, try to perform request. Otherwise, raise an error.
+4. In case of connection problem go to 1.
+5. In case of request problem, go to 3.
+6. Parse and return response.
+
+Withdrawals:
+
+1. Request could be performed <tt>connect_retries</tt> * <tt>request_retries</tt>
+   times. E.g., it could be tried <tt>request_retries</tt> times on each
+   of <tt>connect_retries</tt> servers (when you have 1 server configured,
+   but <tt>connect_retries</tt> is 5, library will try to connect to this
+   server 5 times).
+2. Request could be tried to execute on each server <tt>1..request_retries</tt>
+   times. In case of connection problem, request will be moved to another
+   server immediately.
+
+Usually you will set <tt>connect_retries</tt> equal to servers number,
+so you will be sure each failing request will be performed on all servers.
+This means that if one of servers is live, but others are dead, you request
+will be finally executed successfully.
+
+== Sphinx constants
+
+Most Sphinx API methods expecting for special constants will be passed.
+For example:
+
+  sphinx.set_match_mode(Sphinx::Client::SPH_MATCH_ANY)
+
+Please note that these constants defined in a <tt>Sphinx::Client</tt>
+namespace. You can use symbols or strings instead of these awful
+constants:
+
+  sphinx.set_match_mode(:any)
+  sphinx.set_match_mode('any')
+
+== Setting query filters
+
+Every <tt>set_</tt> method returns <tt>Sphinx::Client</tt> object itself.
+It means that you can chain filtering methods:
+
+  results = Sphinx::Client.new.
+              set_match_mode(:any).
+              set_ranking_mode(:bm25).
+              set_id_range(10, 1000).
+              query('test')
+
+== Example
+
+This simple example illustrates base connection establishing,
+search results retrieving, and excerpts building. Please note
+how does it perform database select using ActiveRecord to
+save the order of records established by Sphinx.
+
+  sphinx = Sphinx::Client.new
+  result = sphinx.query('test')
+  ids = result['matches'].map { |match| match['id'] }
+  posts = Post.all :conditions => { :id => ids },
+                   :order => "FIELD(id,#{ids.join(',')})"
+
+  docs = posts.map(&:body)
+  excerpts = sphinx.build_excerpts(docs, 'index', 'test')
+
+== Support
+
+Source code:
+http://github.com/kpumuk/sphinx
+
+To suggest a feature or report a bug:
+http://github.com/kpumuk/sphinx/issues
+
+Project home page:
 http://kpumuk.info/projects/ror-plugins/sphinx
 
-==Credits
+== Credits
 
 Dmytro Shteflyuk <kpumuk@kpumuk.info> http://kpumuk.info
 
-Andrew Aksyonoff http://sphinxsearch.com/
+Andrew Aksyonoff http://sphinxsearch.com
 
 Special thanks to Alexey Kovyrin <alexey@kovyrin.net> http://blog.kovyrin.net
 
+Special thanks to Mike Perham http://www.mikeperham.com for his awesome
+memcache-client gem, where latest Sphinx gem got new sockets handling from.
+
 ==License
 
 This library is distributed under the terms of the Ruby license.
 You can freely distribute/modify this library.
-

data/Rakefile

@@ -1,6 +1,4 @@
 require 'rake'
-require 'spec/rake/spectask'
-require 'rake/rdoctask'
 
 begin
   require 'jeweler'
@@ -17,20 +15,31 @@ rescue LoadError
   puts 'Jeweler not available. Install it with: sudo gem install jeweler'
 end
 
-desc 'Default: run specs'
-task :default => :spec
+begin
+  require 'spec/rake/spectask'
+
+  desc 'Default: run specs'
+  task :default => :spec
 
-desc 'Test the sphinx plugin'
-Spec::Rake::SpecTask.new(:spec) do |t|
-  t.libs << 'lib'
-  t.pattern = 'spec/*_spec.rb'
+  desc 'Test the sphinx plugin'
+  Spec::Rake::SpecTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = 'spec/*_spec.rb'
+  end
+rescue LoadError
+  puts 'RSpec not available. Install it with: sudo gem install rspec'
 end
 
-desc 'Generate documentation for the sphinx plugin'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Sphinx Client API'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.options = ['--title', 'Sphinx Client API Documentation']
+    if ENV['PRIVATE']
+      t.options.concat ['--protected', '--private']
+    else
+      t.options << '--no-private' 
+    end
+  end
+rescue LoadError
+  puts 'Yard not available. Install it with: sudo gem install yard'
 end

data/VERSION.yml

@@ -2,4 +2,4 @@
 :major: 0
 :minor: 9
 :patch: 10
-:build: 2043
+:build: 2091

data/lib/sphinx.rb

@@ -1,9 +1,21 @@
-require 'socket'
-require 'net/protocol'
-
+# Sphinx Client API
+#
+# Author::    Dmytro Shteflyuk <mailto:kpumuk@kpumuk.info>.
+# Copyright:: Copyright (c) 2006 — 2009 Dmytro Shteflyuk
+# License::   Distributes under the same terms as Ruby
+# Version::   0.9.10-r2091
+# Website::   http://kpumuk.info/projects/ror-plugins/sphinx
+# Sources::   http://github.com/kpumuk/sphinx
+#
+# This library is distributed under the terms of the Ruby license.
+# You can freely distribute/modify this library.
+#
 module Sphinx
 end
 
+require 'socket'
+require 'net/protocol'
+
 require File.dirname(__FILE__) + '/sphinx/request'
 require File.dirname(__FILE__) + '/sphinx/response'
 require File.dirname(__FILE__) + '/sphinx/timeout'

data/lib/sphinx/buffered_io.rb

@@ -1,3 +1,7 @@
+# A simple wrapper around <tt>Net::BufferedIO</tt> performing
+# non-blocking select.
+#
+# @private
 class Sphinx::BufferedIO < Net::BufferedIO # :nodoc:
   BUFSIZE = 1024 * 16
 

data/lib/sphinx/client.rb

@@ -1,120 +1,149 @@
-# = client.rb - Sphinx Client API
-# 
-# Author::    Dmytro Shteflyuk <mailto:kpumuk@kpumuk.info>.
-# Copyright:: Copyright (c) 2006 — 2009 Dmytro Shteflyuk
-# License::   Distributes under the same terms as Ruby
-# Version::   0.9.10-r2043
-# Website::   http://kpumuk.info/projects/ror-plugins/sphinx
-#
-# This library is distributed under the terms of the Ruby license.
-# You can freely distribute/modify this library.
-
-# ==Sphinx Client API
-# 
-# The Sphinx Client API is used to communicate with <tt>searchd</tt>
-# daemon and get search results from Sphinx.
-# 
-# ===Usage
-# 
-#   sphinx = Sphinx::Client.new
-#   result = sphinx.Query('test')
-#   ids = result['matches'].map { |match| match['id'] }.join(',')
-#   posts = Post.find :all, :conditions => "id IN (#{ids})"
-#   
-#   docs = posts.map(&:body)
-#   excerpts = sphinx.BuildExcerpts(docs, 'index', 'test')
-
 module Sphinx
-  # :stopdoc:
-
+  # Base class for all Sphinx errors
   class SphinxError < StandardError; end
+  # Connect error occurred on the API side.
   class SphinxConnectError < SphinxError; end
+  # Request error occurred on the API side.
   class SphinxResponseError < SphinxError; end
+  # Internal error occurred inside searchd.
   class SphinxInternalError < SphinxError; end
+  # Temporary error occurred inside searchd.
   class SphinxTemporaryError < SphinxError; end
+  # Unknown error occurred inside searchd.
   class SphinxUnknownError < SphinxError; end
 
-  # :startdoc:
-
+  # The Sphinx Client API is used to communicate with <tt>searchd</tt>
+  # daemon and perform requests.
+  #
+  # @example
+  #   sphinx = Sphinx::Client.new
+  #   result = sphinx.query('test')
+  #   ids = result['matches'].map { |match| match['id'] }
+  #   posts = Post.all :conditions => { :id => ids },
+  #                    :order => "FIELD(id,#{ids.join(',')})"
+  #
+  #   docs = posts.map(&:body)
+  #   excerpts = sphinx.build_excerpts(docs, 'index', 'test')
+  #
   class Client
-    # :stopdoc:
-  
+    #=================================================================
     # Known searchd commands
-  
+    #=================================================================
+
     # search command
+    # @private
     SEARCHD_COMMAND_SEARCH     = 0
     # excerpt command
+    # @private
     SEARCHD_COMMAND_EXCERPT    = 1
     # update command
+    # @private
     SEARCHD_COMMAND_UPDATE     = 2
     # keywords command
+    # @private
     SEARCHD_COMMAND_KEYWORDS   = 3
     # persist command
+    # @private
     SEARCHD_COMMAND_PERSIST    = 4
     # status command
+    # @private
     SEARCHD_COMMAND_STATUS     = 5
     # query command
+    # @private
     SEARCHD_COMMAND_QUERY      = 6
     # flushattrs command
+    # @private
     SEARCHD_COMMAND_FLUSHATTRS = 7
-  
+
+    #=================================================================
     # Current client-side command implementation versions
-    
+    #=================================================================
+
     # search command version
+    # @private
     VER_COMMAND_SEARCH     = 0x117
     # excerpt command version
+    # @private
     VER_COMMAND_EXCERPT    = 0x100
     # update command version
+    # @private
     VER_COMMAND_UPDATE     = 0x102
     # keywords command version
+    # @private
     VER_COMMAND_KEYWORDS   = 0x100
     # persist command version
+    # @private
     VER_COMMAND_PERSIST    = 0x000
     # status command version
+    # @private
     VER_COMMAND_STATUS     = 0x100
     # query command version
+    # @private
     VER_COMMAND_QUERY      = 0x100
     # flushattrs command version
+    # @private
     VER_COMMAND_FLUSHATTRS = 0x100
-    
+
+    #=================================================================
     # Known searchd status codes
-  
+    #=================================================================
+
     # general success, command-specific reply follows
+    # @private
     SEARCHD_OK      = 0
     # general failure, command-specific reply may follow
+    # @private
     SEARCHD_ERROR   = 1
     # temporaty failure, client should retry later
+    # @private
     SEARCHD_RETRY   = 2
-    # general success, warning message and command-specific reply follow 
-    SEARCHD_WARNING = 3    
+    # general success, warning message and command-specific reply follow
+    # @private
+    SEARCHD_WARNING = 3
 
+    #=================================================================
+    # Some internal attributes to use inside client API
+    #=================================================================
+
+    # List of searchd servers to connect to.
+    # @private
     attr_reader :servers
+    # Connection timeout in seconds.
+    # @private
     attr_reader :timeout
+    # Number of connection retries.
+    # @private
     attr_reader :retries
+    # Request timeout in seconds.
+    # @private
     attr_reader :reqtimeout
+    # Number of request retries.
+    # @private
     attr_reader :reqretries
-    
-    # :startdoc:
-  
+
+    #=================================================================
     # Known match modes
-  
+    #=================================================================
+
     # match all query words
-    SPH_MATCH_ALL       = 0 
+    SPH_MATCH_ALL       = 0
     # match any query word
-    SPH_MATCH_ANY       = 1 
+    SPH_MATCH_ANY       = 1
     # match this exact phrase
-    SPH_MATCH_PHRASE    = 2 
+    SPH_MATCH_PHRASE    = 2
     # match this boolean query
-    SPH_MATCH_BOOLEAN   = 3 
+    SPH_MATCH_BOOLEAN   = 3
     # match this extended query
-    SPH_MATCH_EXTENDED  = 4 
+    SPH_MATCH_EXTENDED  = 4
     # match all document IDs w/o fulltext query, apply filters
     SPH_MATCH_FULLSCAN  = 5
     # extended engine V2 (TEMPORARY, WILL BE REMOVED IN 0.9.8-RELEASE)
     SPH_MATCH_EXTENDED2 = 6
-    
+
+    #=================================================================
     # Known ranking modes (ext2 only)
-  
+    #=================================================================
+
     # default mode, phrase proximity major factor and BM25 minor one
     SPH_RANK_PROXIMITY_BM25 = 0
     # statistical mode, BM25 ranking only (faster but worse quality)
@@ -131,9 +160,11 @@ module Sphinx
     SPH_RANK_FIELDMASK      = 6
     # codename SPH04, phrase proximity + bm25 + head/exact boost
     SPH_RANK_SPH04          = 7
-    
+
+    #=================================================================
     # Known sort modes
-  
+    #=================================================================
+
     # sort by document relevance desc, then by date
     SPH_SORT_RELEVANCE     = 0
     # sort by document date desc, then by relevance desc
@@ -146,23 +177,27 @@ module Sphinx
     SPH_SORT_EXTENDED      = 4
     # sort by arithmetic expression in descending order (eg. "@id + max(@weight,1000)*boost + log(price)")
     SPH_SORT_EXPR          = 5
-    
+
+    #=================================================================
     # Known filter types
-    
+    #=================================================================
+
     # filter by integer values set
     SPH_FILTER_VALUES      = 0
     # filter by integer range
     SPH_FILTER_RANGE       = 1
     # filter by float range
     SPH_FILTER_FLOATRANGE  = 2
-    
+
+    #=================================================================
     # Known attribute types
-  
+    #=================================================================
+
     # this attr is just an integer
     SPH_ATTR_INTEGER   = 1
     # this attr is a timestamp
     SPH_ATTR_TIMESTAMP = 2
-    # this attr is an ordinal string number (integer at search time, 
+    # this attr is an ordinal string number (integer at search time,
     # specially handled at indexing time)
     SPH_ATTR_ORDINAL   = 3
     # this attr is a boolean bit field
@@ -175,23 +210,25 @@ module Sphinx
     SPH_ATTR_STRING    = 7
     # this attr has multiple values (0 or more)
     SPH_ATTR_MULTI     = 0x40000000
-    
+
+    #=================================================================
     # Known grouping functions
-  
+    #=================================================================
+
     # group by day
     SPH_GROUPBY_DAY      = 0
     # group by week
-    SPH_GROUPBY_WEEK     = 1 
+    SPH_GROUPBY_WEEK     = 1
     # group by month
-    SPH_GROUPBY_MONTH    = 2 
+    SPH_GROUPBY_MONTH    = 2
     # group by year
     SPH_GROUPBY_YEAR     = 3
     # group by attribute value
     SPH_GROUPBY_ATTR     = 4
     # group by sequential attrs pair
     SPH_GROUPBY_ATTRPAIR = 5
-    
-    # Constructs the <tt>Sphinx::Client</tt> object and sets options to their default values. 
+
+    # Constructs the <tt>Sphinx::Client</tt> object and sets options to their default values.
     def initialize
       # per-query settings
       @offset        = 0                       # how many records to seek from result-set start (default is 0)
@@ -214,16 +251,16 @@ module Sphinx
       @anchor        = []                      # geographical anchor point
       @indexweights  = []                      # per-index weights
       @ranker        = SPH_RANK_PROXIMITY_BM25 # ranking mode (default is SPH_RANK_PROXIMITY_BM25)
-      @maxquerytime  = 0                       # max query time, milliseconds (default is 0, do not limit) 
+      @maxquerytime  = 0                       # max query time, milliseconds (default is 0, do not limit)
       @fieldweights  = {}                      # per-field-name weights
       @overrides     = []                      # per-query attribute values overrides
       @select        = '*'                     # select-list (attributes or expressions, with optional aliases)
-    
+
       # per-reply fields (for single-query case)
       @error         = ''                      # last error message
       @warning       = ''                      # last warning message
       @connerror     = false                   # connection error vs remote error flag
-      
+
       @reqs          = []                      # requests storage (for multi-query case)
       @mbenc         = ''                      # stored mbstring encoding
       @timeout       = 0                       # connect timeout
@@ -233,58 +270,104 @@ module Sphinx
 
       # per-client-object settings
       # searchd servers list
-      @servers       = [Sphinx::Server.new(self, 'localhost', 3312, false)].freeze
+      @servers       = [Sphinx::Server.new(self, 'localhost', 9312, false)].freeze
       @lastserver    = -1
     end
-  
+
+    #=================================================================
+    # General API functions
+    #=================================================================
+
     # Returns last error message, as a string, in human readable format. If there
     # were no errors during the previous API call, empty string is returned.
     #
-    # You should call it when any other function (such as +Query+) fails (typically,
+    # You should call it when any other function (such as {#query}) fails (typically,
     # the failing function returns false). The returned string will contain the
     # error description.
     #
     # The error message is not reset by this call; so you can safely call it
     # several times if needed.
     #
-    def GetLastError
+    # @return [String] last error message.
+    #
+    # @example
+    #   puts sphinx.last_error
+    #
+    # @see #last_warning
+    # @see #connect_error?
+    #
+    def last_error
       @error
     end
-    
+    alias :GetLastError :last_error
+
     # Returns last warning message, as a string, in human readable format. If there
     # were no warnings during the previous API call, empty string is returned.
     #
-    # You should call it to verify whether your request (such as +Query+) was
+    # You should call it to verify whether your request (such as {#query}) was
     # completed but with warnings. For instance, search query against a distributed
     # index might complete succesfully even if several remote agents timed out.
     # In that case, a warning message would be produced.
-    # 
+    #
     # The warning message is not reset by this call; so you can safely call it
     # several times if needed.
     #
-    def GetLastWarning
+    # @return [String] last warning message.
+    #
+    # @example
+    #   puts sphinx.last_warning
+    #
+    # @see #last_error
+    # @see #connect_error?
+    #
+    def last_warning
       @warning
     end
-    
+    alias :GetLastWarning :last_warning
+
     # Checks whether the last error was a network error on API side, or a
     # remote error reported by searchd. Returns true if the last connection
     # attempt to searchd failed on API side, false otherwise (if the error
     # was remote, or there were no connection attempts at all).
     #
-    def IsConnectError
+    # @return [Boolean] the value indicating whether last error was a
+    #   nework error on API side.
+    #
+    # @example
+    #   puts "Connection failed!" if sphinx.connect_error?
+    #
+    # @see #last_error
+    # @see #last_warning
+    #
+    def connect_error?
       @connerror || false
     end
-    
+    alias :IsConnectError :connect_error?
+
     # Sets searchd host name and TCP port. All subsequent requests will
     # use the new host and port settings. Default +host+ and +port+ are
-    # 'localhost' and 3312, respectively.
+    # 'localhost' and 9312, respectively.
     #
     # Also, you can specify an absolute path to Sphinx's UNIX socket as +host+,
     # in this case pass port as +0+ or +nil+.
     #
-    def SetServer(host, port)
+    # @param [String] host the searchd host name or UNIX socket absolute path.
+    # @param [Integer] port the searchd port name (could be any if UNIX
+    #   socket path specified).
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_server('localhost', 9312)
+    #   sphinx.set_server('/opt/sphinx/var/run/sphinx.sock')
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    # @see #set_servers
+    # @see #set_connect_timeout
+    # @see #set_request_timeout
+    #
+    def set_server(host, port = 9312)
       raise ArgumentError, '"host" argument must be String' unless host.kind_of?(String)
-      
+
       path = nil
       # Check if UNIX socket should be used
       if host[0] == ?/
@@ -298,25 +381,47 @@ module Sphinx
       host = port = nil unless path.nil?
 
       @servers = [Sphinx::Server.new(self, host, port, path)].freeze
+      self
     end
+    alias :SetServer :set_server
 
     # Sets the list of searchd servers. Each subsequent request will use next
     # server in list (round-robin). In case of one server failure, request could
-    # be retried on another server (see +SetConnectTimeout+ and +SetRequestTimeout+).
-    #
-    # Method accepts an +Array+ of +Hash+es, each of them should have :host
-    # and :port (to connect to searchd through network) or :path (an absolute path
-    # to UNIX socket) specified.
-    #
-    def SetServers(servers)
+    # be retried on another server (see {#set_connect_timeout} and
+    # {#set_request_timeout}).
+    #
+    # Method accepts an +Array+ of +Hash+es, each of them should have <tt>:host</tt>
+    # and <tt>:port</tt> (to connect to searchd through network) or <tt>:path</tt>
+    # (an absolute path to UNIX socket) specified.
+    #
+    # @param [Array<Hash>] servers an +Array+ of +Hash+ objects with servers parameters.
+    # @option servers [String] :host the searchd host name or UNIX socket absolute path.
+    # @option servers [String] :path the searchd UNIX socket absolute path.
+    # @option servers [Integer] :port (9312) the searchd port name (skiped when UNIX
+    #   socket path specified)
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_servers([
+    #     { :host => 'browse01.local' }, # default port is 9312
+    #     { :host => 'browse02.local', :port => 9312 },
+    #     { :path => '/opt/sphinx/var/run/sphinx.sock' }
+    #   ])
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    # @see #set_server
+    # @see #set_connect_timeout
+    # @see #set_request_timeout
+    #
+    def set_servers(servers)
       raise ArgumentError, '"servers" argument must be Array'     unless servers.kind_of?(Array)
       raise ArgumentError, '"servers" argument must be not empty' if servers.empty?
-      
+
       @servers = servers.map do |server|
         raise ArgumentError, '"servers" argument must be Array of Hashes' unless server.kind_of?(Hash)
 
         host = server[:path] || server['path'] || server[:host] || server['host']
-        port = server[:port] || server['port']
+        port = server[:port] || server['port'] || 9312
         path = nil
         raise ArgumentError, '"host" argument must be String' unless host.kind_of?(String)
 
@@ -330,11 +435,13 @@ module Sphinx
         end
 
         host = port = nil unless path.nil?
-        
+
         Sphinx::Server.new(self, host, port, path)
       end.freeze
+      self
     end
-    
+    alias :SetServers :set_servers
+
     # Sets the time allowed to spend connecting to the server before giving up
     # and number of retries to perform.
     #
@@ -342,7 +449,7 @@ module Sphinx
     # be returned back to the application in order for application-level error
     # handling to advise the user.
     #
-    # When multiple servers configured through +SetServers+ method, and +retries+
+    # When multiple servers configured through {#set_servers} method, and +retries+
     # number is greater than 1, library will try to connect to another server.
     # In case of single server configured, it will try to reconnect +retries+
     # times.
@@ -350,15 +457,29 @@ module Sphinx
     # Please note, this timeout will only be used for connection establishing, not
     # for regular API requests.
     #
-    def SetConnectTimeout(timeout, retries = 1)
+    # @param [Integer] timeout a connection timeout in seconds.
+    # @param [Integer] retries number of connect retries.
+    # @return [Sphinx::Client] self.
+    #
+    # @example Set connection timeout to 1 second and number of retries to 5
+    #   sphinx.set_connect_timeout(1, 5)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    # @see #set_server
+    # @see #set_servers
+    # @see #set_request_timeout
+    #
+    def set_connect_timeout(timeout, retries = 1)
       raise ArgumentError, '"timeout" argument must be Integer'        unless timeout.respond_to?(:integer?) and timeout.integer?
       raise ArgumentError, '"retries" argument must be Integer'        unless retries.respond_to?(:integer?) and retries.integer?
       raise ArgumentError, '"retries" argument must be greater than 0' unless retries > 0
-      
+
       @timeout = timeout
       @retries = retries
+      self
     end
-    
+    alias :SetConnectTimeout :set_connect_timeout
+
     # Sets the time allowed to spend performing request to the server before giving up
     # and number of retries to perform.
     #
@@ -366,34 +487,82 @@ module Sphinx
     # be returned back to the application in order for application-level error
     # handling to advise the user.
     #
-    # When multiple servers configured through +SetServers+ method, and +retries+
+    # When multiple servers configured through {#set_servers} method, and +retries+
     # number is greater than 1, library will try to do another try with this server
     # (with full reconnect). If connection would fail, behavior depends on
-    # +SetConnectTimeout+ settings.
+    # {#set_connect_timeout} settings.
     #
     # Please note, this timeout will only be used for request performing, not
     # for connection establishing.
     #
-    def SetRequestTimeout(timeout, retries = 1)
+    # @param [Integer] timeout a request timeout in seconds.
+    # @param [Integer] retries number of request retries.
+    # @return [Sphinx::Client] self.
+    #
+    # @example Set request timeout to 1 second and number of retries to 5
+    #   sphinx.set_request_timeout(1, 5)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    # @see #set_server
+    # @see #set_servers
+    # @see #set_connect_timeout
+    #
+    def set_request_timeout(timeout, retries = 1)
       raise ArgumentError, '"timeout" argument must be Integer'        unless timeout.respond_to?(:integer?) and timeout.integer?
       raise ArgumentError, '"retries" argument must be Integer'        unless retries.respond_to?(:integer?) and retries.integer?
       raise ArgumentError, '"retries" argument must be greater than 0' unless retries > 0
-      
+
       @reqtimeout = timeout
       @reqretries = retries
+      self
+    end
+    alias :SetRequestTimeout :set_request_timeout
+
+    # Sets distributed retry count and delay.
+    #
+    # On temporary failures searchd will attempt up to +count+ retries
+    # per agent. +delay+ is the delay between the retries, in milliseconds.
+    # Retries are disabled by default. Note that this call will not make
+    # the API itself retry on temporary failure; it only tells searchd
+    # to do so. Currently, the list of temporary failures includes all
+    # kinds of connection failures and maxed out (too busy) remote agents.
+    #
+    # @param [Integer] count a number of retries to perform.
+    # @param [Integer] delay a delay between the retries.
+    # @return [Sphinx::Client] self.
+    #
+    # @example Perform 5 retries with 200 ms between them
+    #   sphinx.set_retries(5, 200)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    # @see #set_connect_timeout
+    # @see #set_request_timeout
+    #
+    def set_retries(count, delay = 0)
+      raise ArgumentError, '"count" argument must be Integer' unless count.respond_to?(:integer?) and count.integer?
+      raise ArgumentError, '"delay" argument must be Integer' unless delay.respond_to?(:integer?) and delay.integer?
+
+      @retrycount = count
+      @retrydelay = delay
+      self
     end
-   
+    alias :SetRetries :set_retries
+
+    #=================================================================
+    # General query settings
+    #=================================================================
+
     # Sets offset into server-side result set (+offset+) and amount of matches to
     # return to client starting from that offset (+limit+). Can additionally control
     # maximum server-side result set size for current query (+max_matches+) and the
     # threshold amount of matches to stop searching at (+cutoff+). All parameters
     # must be non-negative integers.
     #
-    # First two parameters to +SetLimits+ are identical in behavior to MySQL LIMIT
+    # First two parameters to {#set_limits} are identical in behavior to MySQL LIMIT
     # clause. They instruct searchd to return at most +limit+ matches starting from
     # match number +offset+. The default offset and limit settings are +0+ and +20+,
     # that is, to return first +20+ matches.
-    # 
+    #
     # +max_matches+ setting controls how much matches searchd will keep in RAM
     # while searching. All matching documents will be normally processed, ranked,
     # filtered, and sorted even if max_matches is set to +1+. But only best +N+
@@ -415,12 +584,23 @@ module Sphinx
     # searchd to forcibly stop search query once $cutoff matches had been found
     # and processed.
     #
-    def SetLimits(offset, limit, max = 0, cutoff = 0)
+    # @param [Integer] offset an offset into server-side result set.
+    # @param [Integer] limit an amount of matches to return.
+    # @param [Integer] max a maximum server-side result set size.
+    # @param [Integer] cutoff a threshold amount of matches to stop searching at.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_limits(100, 50, 1000, 5000)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    def set_limits(offset, limit, max = 0, cutoff = 0)
       raise ArgumentError, '"offset" argument must be Integer' unless offset.respond_to?(:integer?) and offset.integer?
       raise ArgumentError, '"limit" argument must be Integer'  unless limit.respond_to?(:integer?)  and limit.integer?
       raise ArgumentError, '"max" argument must be Integer'    unless max.respond_to?(:integer?)    and max.integer?
       raise ArgumentError, '"cutoff" argument must be Integer' unless cutoff.respond_to?(:integer?) and cutoff.integer?
-      
+
       raise ArgumentError, '"offset" argument should be greater or equal to zero' unless offset >= 0
       raise ArgumentError, '"limit" argument should be greater to zero'           unless limit > 0
       raise ArgumentError, '"max" argument should be greater or equal to zero'    unless max >= 0
@@ -430,35 +610,176 @@ module Sphinx
       @limit = limit
       @maxmatches = max if max > 0
       @cutoff = cutoff if cutoff > 0
+      self
     end
-    
+    alias :SetLimits :set_limits
+
     # Sets maximum search query time, in milliseconds. Parameter must be a
     # non-negative integer. Default valus is +0+ which means "do not limit".
     #
-    # Similar to +cutoff+ setting from +SetLimits+, but limits elapsed query
+    # Similar to +cutoff+ setting from {#set_limits}, but limits elapsed query
     # time instead of processed matches count. Local search queries will be
     # stopped once that much time has elapsed. Note that if you're performing
     # a search which queries several local indexes, this limit applies to each
     # index separately.
     #
-    def SetMaxQueryTime(max)
+    # @param [Integer] max maximum search query time in milliseconds.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_max_query_time(200)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    def set_max_query_time(max)
       raise ArgumentError, '"max" argument must be Integer' unless max.respond_to?(:integer?) and max.integer?
       raise ArgumentError, '"max" argument should be greater or equal to zero' unless max >= 0
 
       @maxquerytime = max
+      self
     end
-    
+    alias :SetMaxQueryTime :set_max_query_time
+
+    # Sets temporary (per-query) per-document attribute value overrides. Only
+    # supports scalar attributes. +values+ must be a +Hash+ that maps document
+    # IDs to overridden attribute values.
+    #
+    # Override feature lets you "temporary" update attribute values for some
+    # documents within a single query, leaving all other queries unaffected.
+    # This might be useful for personalized data. For example, assume you're
+    # implementing a personalized search function that wants to boost the posts
+    # that the user's friends recommend. Such data is not just dynamic, but
+    # also personal; so you can't simply put it in the index because you don't
+    # want everyone's searches affected. Overrides, on the other hand, are local
+    # to a single query and invisible to everyone else. So you can, say, setup
+    # a "friends_weight" value for every document, defaulting to 0, then
+    # temporary override it with 1 for documents 123, 456 and 789 (recommended
+    # by exactly the friends of current user), and use that value when ranking.
+    #
+    # You can specify attribute type as String ("integer", "float", etc),
+    # Symbol (:integer, :float, etc), or
+    # Fixnum constant (SPH_ATTR_INTEGER, SPH_ATTR_FLOAT, etc).
+    #
+    # @param [String, Symbol] attribute an attribute name to override values of.
+    # @param [Integer, String, Symbol] attrtype attribute type.
+    # @param [Hash] values a +Hash+ that maps document IDs to overridden attribute values.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_override(:friends_weight, :integer, {123 => 1, 456 => 1, 789 => 1})
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setoverride Section 6.2.3, "SetOverride"
+    #
+    def set_override(attribute, attrtype, values)
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
+
+      case attrtype
+        when String, Symbol
+          begin
+            attrtype = self.class.const_get("SPH_ATTR_#{attrtype.to_s.upcase}")
+          rescue NameError
+            raise ArgumentError, "\"attrtype\" argument value \"#{attrtype}\" is invalid"
+          end
+        when Fixnum
+          raise ArgumentError, "\"attrtype\" argument value \"#{attrtype}\" is invalid" unless (SPH_ATTR_INTEGER..SPH_ATTR_BIGINT).include?(attrtype)
+        else
+          raise ArgumentError, '"attrtype" argument must be Fixnum, String, or Symbol'
+      end
+
+      raise ArgumentError, '"values" argument must be Hash' unless values.kind_of?(Hash)
+
+      values.each do |id, value|
+        raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless id.respond_to?(:integer?) and id.integer?
+        case attrtype
+          when SPH_ATTR_TIMESTAMP
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless (value.respond_to?(:integer?) and value.integer?) or value.kind_of?(Time)
+          when SPH_ATTR_FLOAT
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Float or Integer' unless value.kind_of?(Float) or (value.respond_to?(:integer?) and value.integer?)
+          else
+            # SPH_ATTR_INTEGER, SPH_ATTR_ORDINAL, SPH_ATTR_BOOL, SPH_ATTR_BIGINT
+            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer' unless value.respond_to?(:integer?) and value.integer?
+        end
+      end
+
+      @overrides << { 'attr' => attribute.to_s, 'type' => attrtype, 'values' => values }
+      self
+    end
+    alias :SetOverride :set_override
+
+    # Sets the select clause, listing specific attributes to fetch, and
+    # expressions to compute and fetch. Clause syntax mimics SQL.
+    #
+    # {#set_select} is very similar to the part of a typical SQL query between
+    # +SELECT+ and +FROM+. It lets you choose what attributes (columns) to
+    # fetch, and also what expressions over the columns to compute and fetch.
+    # A certain difference from SQL is that expressions must always be aliased
+    # to a correct identifier (consisting of letters and digits) using +AS+
+    # keyword. SQL also lets you do that but does not require to. Sphinx enforces
+    # aliases so that the computation results can always be returned under a
+    # "normal" name in the result set, used in other clauses, etc.
+    #
+    # Everything else is basically identical to SQL. Star ('*') is supported.
+    # Functions are supported. Arbitrary amount of expressions is supported.
+    # Computed expressions can be used for sorting, filtering, and grouping,
+    # just as the regular attributes.
+    #
+    # Starting with version 0.9.9-rc2, aggregate functions (<tt>AVG()</tt>,
+    # <tt>MIN()</tt>, <tt>MAX()</tt>, <tt>SUM()</tt>) are supported when using
+    # <tt>GROUP BY</tt>.
+    #
+    # Expression sorting (Section 4.5, “SPH_SORT_EXPR mode”) and geodistance
+    # functions ({#set_geo_anchor}) are now internally implemented
+    # using this computed expressions mechanism, using magic names '<tt>@expr</tt>'
+    # and '<tt>@geodist</tt>' respectively.
+    #
+    # @param [String] select a select clause, listing specific attributes to fetch.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_select('*, @weight+(user_karma+ln(pageviews))*0.1 AS myweight')
+    #   sphinx.set_select('exp_years, salary_gbp*{$gbp_usd_rate} AS salary_usd, IF(age>40,1,0) AS over40')
+    #   sphinx.set_select('*, AVG(price) AS avgprice')
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#sort-expr Section 4.5, "SPH_SORT_EXPR mode"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setgeoanchor Section 6.4.5, "SetGeoAnchor"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setselect Section 6.2.4, "SetSelect"
+    #
+    def set_select(select)
+      raise ArgumentError, '"select" argument must be String' unless select.kind_of?(String)
+
+      @select = select
+      self
+    end
+    alias :SetSelect :set_select
+
+    #=================================================================
+    # Full-text search query settings
+    #=================================================================
+
     # Sets full-text query matching mode.
     #
     # Parameter must be a +Fixnum+ constant specifying one of the known modes
     # (+SPH_MATCH_ALL+, +SPH_MATCH_ANY+, etc), +String+ with identifier (<tt>"all"</tt>,
     # <tt>"any"</tt>, etc), or a +Symbol+ (<tt>:all</tt>, <tt>:any</tt>, etc).
     #
-    # Corresponding sections in Sphinx reference manual:
-    # * {Section 4.1, "Matching modes"}[http://www.sphinxsearch.com/docs/current.html#matching-modes] for details.
-    # * {Section 6.3.1, "SetMatchMode"}[http://www.sphinxsearch.com/docs/current.html#api-func-setmatchmode] for details.
+    # @param [Integer, String, Symbol] mode full-text query matching mode.
+    # @return [Sphinx::Client] self.
     #
-    def SetMatchMode(mode)
+    # @example
+    #   sphinx.set_match_mode(Sphinx::Client::SPH_MATCH_ALL)
+    #   sphinx.set_match_mode(:all)
+    #   sphinx.set_match_mode('all')
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#matching-modes Section 4.1, "Matching modes"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setmatchmode Section 6.3.1, "SetMatchMode"
+    #
+    def set_match_mode(mode)
       case mode
         when String, Symbol
           begin
@@ -473,14 +794,33 @@ module Sphinx
       end
 
       @mode = mode
+      self
     end
-    
-    # Set ranking mode.
+    alias :SetMatchMode :set_match_mode
+
+    # Sets ranking mode. Only available in +SPH_MATCH_EXTENDED2+
+    # matching mode at the time of this writing. Parameter must be a
+    # constant specifying one of the known modes.
     #
     # You can specify ranking mode as String ("proximity_bm25", "bm25", etc),
     # Symbol (:proximity_bm25, :bm25, etc), or
     # Fixnum constant (SPH_RANK_PROXIMITY_BM25, SPH_RANK_BM25, etc).
-    def SetRankingMode(ranker)
+    #
+    # @param [Integer, String, Symbol] ranker ranking mode.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_ranking_mode(Sphinx::Client::SPH_RANK_BM25)
+    #   sphinx.set_ranking_mode(:bm25)
+    #   sphinx.set_ranking_mode('bm25')
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#matching-modes Section 4.1, "Matching modes"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setmatchmode Section 6.3.1, "SetMatchMode"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setrankingmode Section 6.3.2, "SetRankingMode"
+    #
+    def set_ranking_mode(ranker)
       case ranker
         when String, Symbol
           begin
@@ -495,14 +835,33 @@ module Sphinx
       end
 
       @ranker = ranker
+      self
     end
-    
+    alias :SetRankingMode :set_ranking_mode
+
     # Set matches sorting mode.
     #
     # You can specify sorting mode as String ("relevance", "attr_desc", etc),
     # Symbol (:relevance, :attr_desc, etc), or
     # Fixnum constant (SPH_SORT_RELEVANCE, SPH_SORT_ATTR_DESC, etc).
-    def SetSortMode(mode, sortby = '')
+    #
+    # @param [Integer, String, Symbol] mode matches sorting mode.
+    # @param [String] sortby sorting clause, with the syntax depending on
+    #   specific mode. Should be specified unless sorting mode is
+    #   +SPH_SORT_RELEVANCE+.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_sort_mode(Sphinx::Client::SPH_SORT_ATTR_ASC, 'attr')
+    #   sphinx.set_sort_mode(:attr_asc, 'attr')
+    #   sphinx.set_sort_mode('attr_asc', 'attr')
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#sorting-modes Section 4.5, "Sorting modes"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setsortmode Section 6.3.3, "SetSortMode"
+    #
+    def set_sort_mode(mode, sortby = '')
       case mode
         when String, Symbol
           begin
@@ -521,27 +880,69 @@ module Sphinx
 
       @sort = mode
       @sortby = sortby
+      self
     end
-    
-    # Bind per-field weights by order.
+    alias :SetSortMode :set_sort_mode
+
+    # Binds per-field weights in the order of appearance in the index.
+    #
+    # @param [Array<Integer>] weights an +Array+ of integer per-field weights.
+    # @return [Sphinx::Client] self.
     #
-    # DEPRECATED; use SetFieldWeights() instead.
-    def SetWeights(weights)
+    # @example
+    #   sphinx.set_weights([1, 3, 5])
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @deprecated Use {#set_field_weights} instead.
+    # @see #set_field_weights
+    #
+    def set_weights(weights)
       raise ArgumentError, '"weights" argument must be Array' unless weights.kind_of?(Array)
       weights.each do |weight|
         raise ArgumentError, '"weights" argument must be Array of integers' unless weight.respond_to?(:integer?) and weight.integer?
       end
 
       @weights = weights
+      self
     end
+    alias :SetWeights :set_weights
 
-    # Bind per-field weights by name.
+    # Binds per-field weights by name. Parameter must be a +Hash+
+    # mapping string field names to integer weights.
+    #
+    # Match ranking can be affected by per-field weights. For instance,
+    # see Section 4.4, "Weighting" for an explanation how phrase
+    # proximity ranking is affected. This call lets you specify what
+    # non-default weights to assign to different full-text fields.
+    #
+    # The weights must be positive 32-bit integers. The final weight
+    # will be a 32-bit integer too. Default weight value is 1. Unknown
+    # field names will be silently ignored.
+    #
+    # There is no enforced limit on the maximum weight value at the
+    # moment. However, beware that if you set it too high you can
+    # start hitting 32-bit wraparound issues. For instance, if
+    # you set a weight of 10,000,000 and search in extended mode,
+    # then maximum possible weight will be equal to 10 million (your
+    # weight) by 1 thousand (internal BM25 scaling factor, see
+    # Section 4.4, “Weighting”) by 1 or more (phrase proximity rank).
+    # The result is at least 10 billion that does not fit in 32 bits
+    # and will be wrapped around, producing unexpected results.
+    #
+    # @param [Hash] weights a +Hash+ mapping string field names to
+    #   integer weights.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_field_weights(:title => 20, :text => 10)
     #
-    # Takes string (field name) to integer (field weight) hash as an argument.
-    # * Takes precedence over SetWeights().
-    # * Unknown names will be silently ignored.
-    # * Unbound fields will be silently given a weight of 1.
-    def SetFieldWeights(weights)
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#weighting Section 4.4, "Weighting"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setfieldweights Section 6.3.5, "SetFieldWeights"
+    #
+    def set_field_weights(weights)
       raise ArgumentError, '"weights" argument must be Hash' unless weights.kind_of?(Hash)
       weights.each do |name, weight|
         unless (name.kind_of?(String) or name.kind_of?(Symbol)) and (weight.respond_to?(:integer?) and weight.integer?)
@@ -550,37 +951,119 @@ module Sphinx
       end
 
       @fieldweights = weights
+      self
     end
-    
-    # Bind per-index weights by name.
-    def SetIndexWeights(weights)
+    alias :SetFieldWeights :set_field_weights
+
+    # Sets per-index weights, and enables weighted summing of match
+    # weights across different indexes. Parameter must be a hash
+    # (associative array) mapping string index names to integer
+    # weights. Default is empty array that means to disable weighting
+    # summing.
+    #
+    # When a match with the same document ID is found in several
+    # different local indexes, by default Sphinx simply chooses the
+    # match from the index specified last in the query. This is to
+    # support searching through partially overlapping index partitions.
+    #
+    # However in some cases the indexes are not just partitions,
+    # and you might want to sum the weights across the indexes
+    # instead of picking one. {#set_index_weights} lets you do that.
+    # With summing enabled, final match weight in result set will be
+    # computed as a sum of match weight coming from the given index
+    # multiplied by respective per-index weight specified in this
+    # call. Ie. if the document 123 is found in index A with the
+    # weight of 2, and also in index B with the weight of 3, and
+    # you called {#set_index_weights} with <tt>{"A"=>100, "B"=>10}</tt>,
+    # the final weight return to the client will be 2*100+3*10 = 230.
+    #
+    # @param [Hash] weights a +Hash+ mapping string index names to
+    #   integer weights.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_field_weights(:fresh => 20, :archived => 10)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setindexweights Section 6.3.6, "SetIndexWeights"
+    #
+    def set_index_weights(weights)
       raise ArgumentError, '"weights" argument must be Hash' unless weights.kind_of?(Hash)
       weights.each do |index, weight|
         unless (index.kind_of?(String) or index.kind_of?(Symbol)) and (weight.respond_to?(:integer?) and weight.integer?)
           raise ArgumentError, '"weights" argument must be Hash map of strings to integers'
         end
       end
-      
+
       @indexweights = weights
+      self
     end
+    alias :SetIndexWeights :set_index_weights
     
-    # Set IDs range to match.
-    # 
-    # Only match records if document ID is beetwen <tt>min_id</tt> and <tt>max_id</tt> (inclusive). 
-    def SetIDRange(min, max)
+    #=================================================================
+    # Result set filtering settings
+    #=================================================================
+
+    # Sets an accepted range of document IDs. Parameters must be integers.
+    # Defaults are 0 and 0; that combination means to not limit by range.
+    #
+    # After this call, only those records that have document ID between
+    # +min+ and +max+ (including IDs exactly equal to +min+ or +max+)
+    # will be matched.
+    #
+    # @param [Integer] min min document ID.
+    # @param [Integer] min max document ID.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_id_range(10, 1000)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setidrange Section 6.4.1, "SetIDRange"
+    #
+    def set_id_range(min, max)
       raise ArgumentError, '"min" argument must be Integer' unless min.respond_to?(:integer?) and min.integer?
       raise ArgumentError, '"max" argument must be Integer' unless max.respond_to?(:integer?) and max.integer?
       raise ArgumentError, '"max" argument greater or equal to "min"' unless min <= max
 
       @min_id = min
       @max_id = max
+      self
     end
-    
-    # Set values filter.
-    # 
-    # Only match those records where <tt>attribute</tt> column values
-    # are in specified set.
-    def SetFilter(attribute, values, exclude = false)
+    alias :SetIDRange :set_id_range
+
+    # Adds new integer values set filter.
+    #
+    # On this call, additional new filter is added to the existing
+    # list of filters. $attribute must be a string with attribute
+    # name. +values+ must be a plain array containing integer
+    # values. +exclude+ must be a boolean value; it controls
+    # whether to accept the matching documents (default mode, when
+    # +exclude+ is +false+) or reject them.
+    #
+    # Only those documents where +attribute+ column value stored in
+    # the index matches any of the values from +values+ array will
+    # be matched (or rejected, if +exclude+ is +true+).
+    #
+    # @param [String, Symbol] attribute an attribute name to filter by.
+    # @param [Array<Integer>] values an +Array+ of integers with given attribute values.
+    # @param [Boolean] exclude indicating whether documents with given attribute
+    #   matching specified values should be excluded from search results.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_filter(:group_id, [10, 15, 20])
+    #   sphinx.set_filter(:group_id, [10, 15, 20], true)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setfilter Section 6.4.2, "SetFilter"
+    # @see #set_filter_range
+    # @see #set_filter_float_range
+    #
+    def set_filter(attribute, values, exclude = false)
       raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
       raise ArgumentError, '"values" argument must be Array'               unless values.kind_of?(Array)
       raise ArgumentError, '"values" argument must not be empty'           if values.empty?
@@ -589,94 +1072,194 @@ module Sphinx
       values.each do |value|
         raise ArgumentError, '"values" argument must be Array of Integer' unless value.respond_to?(:integer?) and value.integer?
       end
-    
+
       @filters << { 'type' => SPH_FILTER_VALUES, 'attr' => attribute.to_s, 'exclude' => exclude, 'values' => values }
+      self
     end
-    
-    # Set range filter.
-    # 
-    # Only match those records where <tt>attribute</tt> column value
-    # is beetwen <tt>min</tt> and <tt>max</tt> (including <tt>min</tt> and <tt>max</tt>).
-    def SetFilterRange(attribute, min, max, exclude = false)
+    alias :SetFilter :set_filter
+
+    # Adds new integer range filter.
+    #
+    # On this call, additional new filter is added to the existing
+    # list of filters. +attribute+ must be a string with attribute
+    # name. +min+ and +max+ must be integers that define the acceptable
+    # attribute values range (including the boundaries). +exclude+
+    # must be a boolean value; it controls whether to accept the
+    # matching documents (default mode, when +exclude+ is false) or
+    # reject them.
+    #
+    # Only those documents where +attribute+ column value stored
+    # in the index is between +min+ and +max+ (including values
+    # that are exactly equal to +min+ or +max+) will be matched
+    # (or rejected, if +exclude+ is true).
+    #
+    # @param [String, Symbol] attribute an attribute name to filter by.
+    # @param [Integer] min min value of the given attribute.
+    # @param [Integer] max max value of the given attribute.
+    # @param [Boolean] exclude indicating whether documents with given attribute
+    #   matching specified boundaries should be excluded from search results.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_filter_range(:group_id, 10, 20)
+    #   sphinx.set_filter_range(:group_id, 10, 20, true)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setfilterrange Section 6.4.3, "SetFilterRange"
+    # @see #set_filter
+    # @see #set_filter_float_range
+    #
+    def set_filter_range(attribute, min, max, exclude = false)
       raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
       raise ArgumentError, '"min" argument must be Integer'                unless min.respond_to?(:integer?) and min.integer?
       raise ArgumentError, '"max" argument must be Integer'                unless max.respond_to?(:integer?) and max.integer?
       raise ArgumentError, '"max" argument greater or equal to "min"'      unless min <= max
       raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
-    
+
       @filters << { 'type' => SPH_FILTER_RANGE, 'attr' => attribute.to_s, 'exclude' => exclude, 'min' => min, 'max' => max }
+      self
     end
-    
-    # Set float range filter.
-    #
-    # Only match those records where <tt>attribute</tt> column value
-    # is beetwen <tt>min</tt> and <tt>max</tt> (including <tt>min</tt> and <tt>max</tt>).
-    def SetFilterFloatRange(attribute, min, max, exclude = false)
+    alias :SetFilterRange :set_filter_range
+
+    # Adds new float range filter.
+    #
+    # On this call, additional new filter is added to the existing
+    # list of filters. +attribute+ must be a string with attribute name.
+    # +min+ and +max+ must be floats that define the acceptable
+    # attribute values range (including the boundaries). +exclude+ must
+    # be a boolean value; it controls whether to accept the matching
+    # documents (default mode, when +exclude+ is false) or reject them.
+    #
+    # Only those documents where +attribute+ column value stored in
+    # the index is between +min+ and +max+ (including values that are
+    # exactly equal to +min+ or +max+) will be matched (or rejected,
+    # if +exclude+ is true).
+    #
+    # @param [String, Symbol] attribute an attribute name to filter by.
+    # @param [Integer, Float] min min value of the given attribute.
+    # @param [Integer, Float] max max value of the given attribute.
+    # @param [Boolean] exclude indicating whether documents with given attribute
+    #   matching specified boundaries should be excluded from search results.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_filter_float_range(:group_id, 10.5, 20)
+    #   sphinx.set_filter_float_range(:group_id, 10.5, 20, true)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setfilterfloatrange Section 6.4.4, "SetFilterFloatRange"
+    # @see #set_filter
+    # @see #set_filter_range
+    #
+    def set_filter_float_range(attribute, min, max, exclude = false)
       raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String) or attribute.kind_of?(Symbol)
       raise ArgumentError, '"min" argument must be Float or Integer'       unless min.kind_of?(Float) or (min.respond_to?(:integer?) and min.integer?)
       raise ArgumentError, '"max" argument must be Float or Integer'       unless max.kind_of?(Float) or (max.respond_to?(:integer?) and max.integer?)
       raise ArgumentError, '"max" argument greater or equal to "min"'      unless min <= max
       raise ArgumentError, '"exclude" argument must be Boolean'            unless exclude.kind_of?(TrueClass) or exclude.kind_of?(FalseClass)
-    
+
       @filters << { 'type' => SPH_FILTER_FLOATRANGE, 'attr' => attribute.to_s, 'exclude' => exclude, 'min' => min.to_f, 'max' => max.to_f }
+      self
     end
-    
-    # Setup anchor point for geosphere distance calculations.
-    #
-    # Required to use <tt>@geodist</tt> in filters and sorting
-    # distance will be computed to this point. Latitude and longitude 
-    # must be in radians.
-    #
-    # * <tt>attrlat</tt> -- is the name of latitude attribute
-    # * <tt>attrlong</tt> -- is the name of longitude attribute
-    # * <tt>lat</tt> -- is anchor point latitude, in radians
-    # * <tt>long</tt> -- is anchor point longitude, in radians
-    def SetGeoAnchor(attrlat, attrlong, lat, long)
+    alias :SetFilterFloatRange :set_filter_float_range
+
+    # Sets anchor point for and geosphere distance (geodistance)
+    # calculations, and enable them.
+    #
+    # +attrlat+ and +attrlong+ must be strings that contain the names
+    # of latitude and longitude attributes, respectively. +lat+ and
+    # +long+ are floats that specify anchor point latitude and
+    # longitude, in radians.
+    #
+    # Once an anchor point is set, you can use magic <tt>"@geodist"</tt>
+    # attribute name in your filters and/or sorting expressions.
+    # Sphinx will compute geosphere distance between the given anchor
+    # point and a point specified by latitude and lognitude attributes
+    # from each full-text match, and attach this value to the resulting
+    # match. The latitude and longitude values both in {#set_geo_anchor}
+    # and the index attribute data are expected to be in radians.
+    # The result will be returned in meters, so geodistance value of
+    # 1000.0 means 1 km. 1 mile is approximately 1609.344 meters.
+    #
+    # @param [String, Symbol] attrlat a name of latitude attribute.
+    # @param [String, Symbol] attrlong a name of longitude attribute.
+    # @param [Integer, Float] lat an anchor point latitude, in radians.
+    # @param [Integer, Float] long an anchor point longitude, in radians.
+    # @return [Sphinx::Client] self.
+    #
+    # @example
+    #   sphinx.set_geo_anchor(:latitude, :longitude, 192.5, 143.5)
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setgeoanchor Section 6.4.5, "SetGeoAnchor"
+    #
+    def set_geo_anchor(attrlat, attrlong, lat, long)
       raise ArgumentError, '"attrlat" argument must be String or Symbol'  unless attrlat.kind_of?(String)  or attrlat.kind_of?(Symbol)
       raise ArgumentError, '"attrlong" argument must be String or Symbol' unless attrlong.kind_of?(String) or attrlong.kind_of?(Symbol)
       raise ArgumentError, '"lat" argument must be Float or Integer'      unless lat.kind_of?(Float)  or (lat.respond_to?(:integer?)  and lat.integer?)
       raise ArgumentError, '"long" argument must be Float or Integer'     unless long.kind_of?(Float) or (long.respond_to?(:integer?) and long.integer?)
 
       @anchor = { 'attrlat' => attrlat.to_s, 'attrlong' => attrlong.to_s, 'lat' => lat.to_f, 'long' => long.to_f }
+      self
     end
+    alias :SetGeoAnchor :set_geo_anchor
     
-    # Set grouping attribute and function.
+    #=================================================================
+    # GROUP BY settings
+    #=================================================================
+
+    # Sets grouping attribute, function, and groups sorting mode; and
+    # enables grouping (as described in Section 4.6, "Grouping (clustering) search results").
     #
-    # In grouping mode, all matches are assigned to different groups
-    # based on grouping function value.
+    # +attribute+ is a string that contains group-by attribute name.
+    # +func+ is a constant that chooses a function applied to the
+    # attribute value in order to compute group-by key. +groupsort+
+    # is a clause that controls how the groups will be sorted. Its
+    # syntax is similar to that described in Section 4.5,
+    # "SPH_SORT_EXTENDED mode".
     #
-    # Each group keeps track of the total match count, and the best match
-    # (in this group) according to current sorting function.
+    # Grouping feature is very similar in nature to <tt>GROUP BY</tt> clause
+    # from SQL. Results produces by this function call are going to
+    # be the same as produced by the following pseudo code:
     #
-    # The final result set contains one best match per group, with
-    # grouping function value and matches count attached.
+    #   SELECT ... GROUP BY func(attribute) ORDER BY groupsort
     #
-    # Groups in result set could be sorted by any sorting clause,
-    # including both document attributes and the following special
-    # internal Sphinx attributes:
+    # Note that it's +groupsort+ that affects the order of matches in
+    # the final result set. Sorting mode (see {#set_sort_mode}) affect
+    # the ordering of matches within group, ie. what match will be
+    # selected as the best one from the group. So you can for instance
+    # order the groups by matches count and select the most relevant
+    # match within each group at the same time.
     #
-    # * @id - match document ID;
-    # * @weight, @rank, @relevance -  match weight;
-    # * @group - groupby function value;
-    # * @count - amount of matches in group.
+    # Starting with version 0.9.9-rc2, aggregate functions (<tt>AVG()</tt>,
+    # <tt>MIN()</tt>, <tt>MAX()</tt>, <tt>SUM()</tt>) are supported
+    # through {#set_select} API call when using <tt>GROUP BY</tt>.
+    #
+    # You can specify group function and attribute as String
+    # ("attr", "day", etc), Symbol (:attr, :day, etc), or
+    # Fixnum constant (SPH_GROUPBY_ATTR, SPH_GROUPBY_DAY, etc).
+    #
+    # @param [String, Symbol] attribute an attribute name to group by.
+    # @param [Integer, String, Symbol] func a grouping function.
+    # @param [String] groupsort a groups sorting mode.
+    # @return [Sphinx::Client] self.
     #
-    # the default mode is to sort by groupby value in descending order,
-    # ie. by '@group desc'.
+    # @example
+    #   sphinx.set_group_by(:tag_id, :attr)
     #
-    # 'total_found' would contain total amount of matching groups over
-    # the whole index.
+    # @raise [ArgumentError] Occurred when parameters are invalid.
     #
-    # WARNING: grouping is done in fixed memory and thus its results
-    # are only approximate; so there might be more groups reported
-    # in total_found than actually present. @count might also
-    # be underestimated. 
+    # @see http://www.sphinxsearch.com/docs/current.html#clustering Section 4.6, "Grouping (clustering) search results"
+    # @see http://www.sphinxsearch.com/docs/current.html#sort-extended Section 4.5, "SPH_SORT_EXTENDED mode"
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setgroupby Section 6.5.1, "SetGroupBy"
+    # @see #set_sort_mode
+    # @see #set_select
+    # @see #set_group_distinct
     #
-    # For example, if sorting by relevance and grouping by "published"
-    # attribute with SPH_GROUPBY_DAY function, then the result set will
-    # contain one most relevant match per each day when there were any
-    # matches published, with day number and per-day match count attached,
-    # and sorted by day number in descending order (ie. recent days first).
-    def SetGroupBy(attribute, func, groupsort = '@group desc')
+    def set_group_by(attribute, func, groupsort = '@group desc')
       raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String)  or attribute.kind_of?(Symbol)
       raise ArgumentError, '"groupsort" argument must be String'           unless groupsort.kind_of?(String)
 
@@ -696,217 +1279,311 @@ module Sphinx
       @groupby = attribute.to_s
       @groupfunc = func
       @groupsort = groupsort
+      self
     end
-    
-    # Set count-distinct attribute for group-by queries.
-    def SetGroupDistinct(attribute)
-      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String)  or attribute.kind_of?(Symbol)
+    alias :SetGroupBy :set_group_by
 
-      @groupdistinct = attribute.to_s
-    end
-    
-    # Sets distributed retry count and delay.
+    # Sets attribute name for per-group distinct values count
+    # calculations. Only available for grouping queries.
     #
-    # On temporary failures searchd will attempt up to +count+ retries per
-    # agent. +delay+ is the delay between the retries, in milliseconds. Retries
-    # are disabled by default. Note that this call will not make the API itself
-    # retry on temporary failure; it only tells searchd to do so. Currently,
-    # the list of temporary failures includes all kinds of +connect+
-    # failures and maxed out (too busy) remote agents.
+    # +attribute+ is a string that contains the attribute name. For
+    # each group, all values of this attribute will be stored (as
+    # RAM limits permit), then the amount of distinct values will
+    # be calculated and returned to the client. This feature is
+    # similar to <tt>COUNT(DISTINCT)</tt> clause in standard SQL;
+    # so these Sphinx calls:
     #
-    def SetRetries(count, delay = 0)
-      raise ArgumentError, '"count" argument must be Integer' unless count.respond_to?(:integer?) and count.integer?
-      raise ArgumentError, '"delay" argument must be Integer' unless delay.respond_to?(:integer?) and delay.integer?
-      
-      @retrycount = count
-      @retrydelay = delay
-    end
-    
-    # Sets temporary (per-query) per-document attribute value overrides. Only
-    # supports scalar attributes. +values+ must be a +Hash+ that maps document
-    # IDs to overridden attribute values.
+    #   sphinx.set_group_by(:category, :attr, '@count desc')
+    #   sphinx.set_group_distinct(:vendor)
     #
-    # Override feature lets you "temporary" update attribute values for some
-    # documents within a single query, leaving all other queries unaffected.
-    # This might be useful for personalized data. For example, assume you're
-    # implementing a personalized search function that wants to boost the posts
-    # that the user's friends recommend. Such data is not just dynamic, but
-    # also personal; so you can't simply put it in the index because you don't
-    # want everyone's searches affected. Overrides, on the other hand, are local
-    # to a single query and invisible to everyone else. So you can, say, setup
-    # a "friends_weight" value for every document, defaulting to 0, then
-    # temporary override it with 1 for documents 123, 456 and 789 (recommended
-    # by exactly the friends of current user), and use that value when ranking.
+    # can be expressed using the following SQL clauses:
     #
-    def SetOverride(attrname, attrtype, values)
-      raise ArgumentError, '"attrname" argument must be String or Symbol' unless attrname.kind_of?(String) or attrname.kind_of?(Symbol)
-
-      case attrtype
-        when String, Symbol
-          begin
-            attrtype = self.class.const_get("SPH_ATTR_#{attrtype.to_s.upcase}")
-          rescue NameError
-            raise ArgumentError, "\"attrtype\" argument value \"#{attrtype}\" is invalid"
-          end
-        when Fixnum
-          raise ArgumentError, "\"attrtype\" argument value \"#{attrtype}\" is invalid" unless (SPH_ATTR_INTEGER..SPH_ATTR_BIGINT).include?(attrtype)
-        else
-          raise ArgumentError, '"attrtype" argument must be Fixnum, String, or Symbol'
-      end
-
-      raise ArgumentError, '"values" argument must be Hash' unless values.kind_of?(Hash)
-      
-      values.each do |id, value|
-        raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless id.respond_to?(:integer?) and id.integer?
-        case attrtype
-          when SPH_ATTR_TIMESTAMP
-            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer or Time' unless (value.respond_to?(:integer?) and value.integer?) or value.kind_of?(Time)
-          when SPH_ATTR_FLOAT
-            raise ArgumentError, '"values" argument must be Hash map of Integer to Float or Integer' unless value.kind_of?(Float) or (value.respond_to?(:integer?) and value.integer?)
-          else
-            # SPH_ATTR_INTEGER, SPH_ATTR_ORDINAL, SPH_ATTR_BOOL, SPH_ATTR_BIGINT
-            raise ArgumentError, '"values" argument must be Hash map of Integer to Integer' unless value.respond_to?(:integer?) and value.integer?
-        end
-      end
-
-      @overrides << { 'attr' => attrname.to_s, 'type' => attrtype, 'values' => values }
-    end
-
-    # Sets the select clause, listing specific attributes to fetch, and
-    # expressions to compute and fetch. Clause syntax mimics SQL.
+    #   SELECT id, weight, all-attributes,
+    #     COUNT(DISTINCT vendor) AS @distinct,
+    #     COUNT(*) AS @count
+    #   FROM products
+    #   GROUP BY category
+    #   ORDER BY @count DESC
     #
-    # +SetSelect+ is very similar to the part of a typical SQL query between
-    # +SELECT+ and +FROM+. It lets you choose what attributes (columns) to
-    # fetch, and also what expressions over the columns to compute and fetch.
-    # A certain difference from SQL is that expressions must always be aliased
-    # to a correct identifier (consisting of letters and digits) using +AS+
-    # keyword. SQL also lets you do that but does not require to. Sphinx enforces
-    # aliases so that the computation results can always be returned under a
-    #{ }"normal" name in the result set, used in other clauses, etc.
+    # In the sample pseudo code shown just above, {#set_group_distinct}
+    # call corresponds to <tt>COUNT(DISINCT vendor)</tt> clause only.
+    # <tt>GROUP BY</tt>, <tt>ORDER BY</tt>, and <tt>COUNT(*)</tt>
+    # clauses are all an equivalent of {#set_group_by} settings. Both
+    # queries will return one matching row for each category. In
+    # addition to indexed attributes, matches will also contain
+    # total per-category matches count, and the count of distinct
+    # vendor IDs within each category.
     #
-    # Everything else is basically identical to SQL. Star ('*') is supported.
-    # Functions are supported. Arbitrary amount of expressions is supported.
-    # Computed expressions can be used for sorting, filtering, and grouping,
-    # just as the regular attributes.
+    # @param [String, Symbol] attribute an attribute name.
+    # @return [Sphinx::Client] self.
     #
-    # Starting with version 0.9.9-rc2, aggregate functions (<tt>AVG()</tt>,
-    # <tt>MIN()</tt>, <tt>MAX()</tt>, <tt>SUM()</tt>) are supported when using
-    # <tt>GROUP BY</tt>.
+    # @example
+    #   sphinx.set_group_distinct(:category_id)
     #
-    # Expression sorting (Section 4.5, “SPH_SORT_EXPR mode”) and geodistance
-    # functions (+SetGeoAnchor+) are now internally implemented
-    # using this computed expressions mechanism, using magic names '<tt>@expr</tt>'
-    # and '<tt>@geodist</tt>' respectively.
+    # @raise [ArgumentError] Occurred when parameters are invalid.
     #
-    # Usage example:
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-setgroupdistinct Section 6.5.2, "SetGroupDistinct"
+    # @see #set_group_by
     #
-    #   sphinx.SetSelect('*, @weight+(user_karma+ln(pageviews))*0.1 AS myweight')
-    #   sphinx.SetSelect('exp_years, salary_gbp*{$gbp_usd_rate} AS salary_usd, IF(age>40,1,0) AS over40')
-    #   sphinx.SetSelect('*, AVG(price) AS avgprice')
-    #
-    def SetSelect(select)
-      raise ArgumentError, '"select" argument must be String' unless select.kind_of?(String)
+    def set_group_distinct(attribute)
+      raise ArgumentError, '"attribute" argument must be String or Symbol' unless attribute.kind_of?(String)  or attribute.kind_of?(Symbol)
 
-      @select = select
+      @groupdistinct = attribute.to_s
+      self
     end
-    
+    alias :SetGroupDistinct :set_group_distinct
+
+    #=================================================================
+    # Querying
+    #=================================================================
+
     # Clears all currently set filters.
     #
     # This call is only normally required when using multi-queries. You might want
     # to set different filters for different queries in the batch. To do that,
-    # you should call +ResetFilters+ and add new filters using the respective calls.
+    # you should call {#reset_filters} and add new filters using the respective calls.
+    #
+    # @return [Sphinx::Client] self.
     #
-    # Usage example:
+    # @example
+    #   sphinx.reset_filters
     #
-    #   sphinx.ResetFilters
+    # @see #set_filter
+    # @see #set_filter_range
+    # @see #set_filter_float_range
+    # @see #set_geo_anchor
     #
-    def ResetFilters
+    def reset_filters
       @filters = []
       @anchor = []
+      self
     end
-    
+    alias :ResetFilters :reset_filters
+
     # Clears all currently group-by settings, and disables group-by.
     #
     # This call is only normally required when using multi-queries. You can
-    # change individual group-by settings using +SetGroupBy+ and +SetGroupDistinct+
-    # calls, but you can not disable group-by using those calls. +ResetGroupBy+
+    # change individual group-by settings using {#set_group_by} and {#set_group_distinct}
+    # calls, but you can not disable group-by using those calls. {#reset_group_by}
     # fully resets previous group-by settings and disables group-by mode in the
-    # current state, so that subsequent +AddQuery+ calls can perform non-grouping
+    # current state, so that subsequent {#add_query} calls can perform non-grouping
     # searches.
     #
-    # Usage example:
+    # @return [Sphinx::Client] self.
     #
-    #   sphinx.ResetGroupBy
+    # @example
+    #   sphinx.reset_group_by
     #
-    def ResetGroupBy
+    # @see #set_group_by
+    # @see #set_group_distinct
+    #
+    def reset_group_by
       @groupby       = ''
       @groupfunc     = SPH_GROUPBY_DAY
       @groupsort     = '@group desc'
       @groupdistinct = ''
+      self
     end
-    
+    alias :ResetGroupBy :reset_group_by
+
     # Clear all attribute value overrides (for multi-queries).
-    def ResetOverrides
-      @overrides = []
-    end
-    
-    # Connect to searchd server and run given search query.
     #
-    # <tt>query</tt> is query string
-
-    # <tt>index</tt> is index name (or names) to query. default value is "*" which means
-    # to query all indexes. Accepted characters for index names are letters, numbers,
-    # dash, and underscore; everything else is considered a separator. Therefore,
-    # all the following calls are valid and will search two indexes:
+    # This call is only normally required when using multi-queries. You might want
+    # to set field overrides for different queries in the batch. To do that,
+    # you should call {#reset_overrides} and add new overrides using the
+    # respective calls.
     #
-    #   sphinx.Query('test query', 'main delta')
-    #   sphinx.Query('test query', 'main;delta')
-    #   sphinx.Query('test query', 'main, delta')
+    # @return [Sphinx::Client] self.
     #
-    # Index order matters. If identical IDs are found in two or more indexes,
-    # weight and attribute values from the very last matching index will be used
-    # for sorting and returning to client. Therefore, in the example above,
-    # matches from "delta" index will always "win" over matches from "main".
+    # @example
+    #   sphinx.reset_overrides
     #
-    # Returns false on failure.
-    # Returns hash which has the following keys on success:
-    # 
-    # * <tt>'matches'</tt> -- array of hashes {'weight', 'group', 'id'}, where 'id' is document_id.
-    # * <tt>'total'</tt> -- total amount of matches retrieved (upto SPH_MAX_MATCHES, see sphinx.h)
-    # * <tt>'total_found'</tt> -- total amount of matching documents in index
-    # * <tt>'time'</tt> -- search time
-    # * <tt>'words'</tt> -- hash which maps query terms (stemmed!) to ('docs', 'hits') hash
-    def Query(query, index = '*', comment = '')
+    # @see #set_override
+    #
+    def reset_overrides
+      @overrides = []
+      self
+    end
+    alias :ResetOverrides :reset_overrides
+
+    # Connects to searchd server, runs given search query with
+    # current settings, obtains and returns the result set.
+    #
+    # +query+ is a query string. +index+ is an index name (or names)
+    # string. Returns false and sets {#last_error} message on general
+    # error. Returns search result set on success. Additionally,
+    # the contents of +comment+ are sent to the query log, marked in
+    # square brackets, just before the search terms, which can be very
+    # useful for debugging. Currently, the comment is limited to 128
+    # characters.
+    #
+    # Default value for +index+ is <tt>"*"</tt> that means to query
+    # all local indexes. Characters allowed in index names include
+    # Latin letters (a-z), numbers (0-9), minus sign (-), and
+    # underscore (_); everything else is considered a separator.
+    # Therefore, all of the following samples calls are valid and
+    # will search the same two indexes:
+    #
+    #   sphinx.query('test query', 'main delta')
+    #   sphinx.query('test query', 'main;delta')
+    #   sphinx.query('test query', 'main, delta');
+    #
+    # Index specification order matters. If document with identical
+    # IDs are found in two or more indexes, weight and attribute
+    # values from the very last matching index will be used for
+    # sorting and returning to client (unless explicitly overridden
+    # with {#set_index_weights}). Therefore, in the example above,
+    # matches from "delta" index will always win over matches
+    # from "main".
+    #
+    # On success, {#query} returns a result set that contains some
+    # of the found matches (as requested by {#set_limits}) and
+    # additional general per-query statistics. The result set
+    # is an +Hash+ with the following keys and values:
+    #
+    # <tt>"matches"</tt>::
+    #   Array with small +Hash+es containing document weight and
+    #   attribute values.
+    # <tt>"total"</tt>::
+    #   Total amount of matches retrieved on server (ie. to the server
+    #   side result set) by this query. You can retrieve up to this
+    #   amount of matches from server for this query text with current
+    #   query settings.
+    # <tt>"total_found"</tt>::
+    #   Total amount of matching documents in index (that were found
+    #   and procesed on server).
+    # <tt>"words"</tt>::
+    #   Hash which maps query keywords (case-folded, stemmed, and
+    #   otherwise processed) to a small Hash with per-keyword statitics
+    #   ("docs", "hits").
+    # <tt>"error"</tt>::
+    #   Query error message reported by searchd (string, human readable).
+    #   Empty if there were no errors.
+    # <tt>"warning"</tt>::
+    #   Query warning message reported by searchd (string, human readable).
+    #   Empty if there were no warnings.
+    #
+    # It should be noted that {#query} carries out the same actions as
+    # {#add_query} and {#run_queries} without the intermediate steps; it
+    # is analoguous to a single {#add_query} call, followed by a
+    # corresponding {#run_queries}, then returning the first array
+    # element of matches (from the first, and only, query.)
+    #
+    # @param [String] query a query string.
+    # @param [String] index an index name (or names).
+    # @param [String] comment a comment to be sent to the query log.
+    # @return [Hash, false] result set described above or +false+ on error.
+    #
+    # @example
+    #   sphinx.query('some search text', '*', 'search page')
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-query Section 6.6.1, "Query"
+    # @see #add_query
+    # @see #run_queries
+    #
+    def query(query, index = '*', comment = '')
       @reqs = []
-      
-      self.AddQuery(query, index, comment)
-      results = self.RunQueries
-      
+
+      self.add_query(query, index, comment)
+      results = self.run_queries
+
       # probably network error; error message should be already filled
       return false unless results.instance_of?(Array)
-      
+
       @error = results[0]['error']
       @warning = results[0]['warning']
-      
+
       return false if results[0]['status'] == SEARCHD_ERROR
       return results[0]
     end
-    
-    # Add query to batch.
-    #
-    # Batch queries enable searchd to perform internal optimizations,
-    # if possible; and reduce network connection overheads in all cases.
-    #
-    # For instance, running exactly the same query with different
-    # groupby settings will enable searched to perform expensive
-    # full-text search and ranking operation only once, but compute
-    # multiple groupby results from its output.
+    alias :Query :query
+
+    # Adds additional query with current settings to multi-query batch.
+    # +query+ is a query string. +index+ is an index name (or names)
+    # string. Additionally if provided, the contents of +comment+ are
+    # sent to the query log, marked in square brackets, just before
+    # the search terms, which can be very useful for debugging.
+    # Currently, this is limited to 128 characters. Returns index
+    # to results array returned from {#run_queries}.
+    #
+    # Batch queries (or multi-queries) enable searchd to perform
+    # internal optimizations if possible. They also reduce network
+    # connection overheads and search process creation overheads in all
+    # cases. They do not result in any additional overheads compared
+    # to simple queries. Thus, if you run several different queries
+    # from your web page, you should always consider using multi-queries.
+    # 
+    # For instance, running the same full-text query but with different
+    # sorting or group-by settings will enable searchd to perform
+    # expensive full-text search and ranking operation only once, but
+    # compute multiple group-by results from its output.
+    # 
+    # This can be a big saver when you need to display not just plain
+    # search results but also some per-category counts, such as the
+    # amount of products grouped by vendor. Without multi-query, you
+    # would have to run several queries which perform essentially the
+    # same search and retrieve the same matches, but create result
+    # sets differently. With multi-query, you simply pass all these
+    # queries in a single batch and Sphinx optimizes the redundant
+    # full-text search internally.
+    # 
+    # {#add_query} internally saves full current settings state along
+    # with the query, and you can safely change them afterwards for
+    # subsequent {#add_query} calls. Already added queries will not
+    # be affected; there's actually no way to change them at all.
+    # Here's an example:
+    # 
+    #   sphinx.set_sort_mode(:relevance)
+    #   sphinx.add_query("hello world", "documents")
+    # 
+    #   sphinx.set_sort_mode(:attr_desc, :price)
+    #   sphinx.add_query("ipod", "products")
     #
-    # Parameters are exactly the same as in <tt>Query</tt> call.
-    # Returns index to results array returned by <tt>RunQueries</tt> call.
-    def AddQuery(query, index = '*', comment = '')
+    #   sphinx.add_query("harry potter", "books")
+    # 
+    #   results = sphinx.run_queries
+    #
+    # With the code above, 1st query will search for "hello world"
+    # in "documents" index and sort results by relevance, 2nd query
+    # will search for "ipod" in "products" index and sort results
+    # by price, and 3rd query will search for "harry potter" in
+    # "books" index while still sorting by price. Note that 2nd
+    # {#set_sort_mode} call does not affect the first query (because
+    # it's already added) but affects both other subsequent queries.
+    # 
+    # Additionally, any filters set up before an {#add_query} will
+    # fall through to subsequent queries. So, if {#set_filter} is
+    # called before the first query, the same filter will be in
+    # place for the second (and subsequent) queries batched through
+    # {#add_query} unless you call {#reset_filters} first. Alternatively,
+    # you can add additional filters as well.
+    # 
+    # This would also be true for grouping options and sorting options;
+    # no current sorting, filtering, and grouping settings are affected
+    # by this call; so subsequent queries will reuse current query settings.
+    # 
+    # {#add_query} returns an index into an array of results that will
+    # be returned from {#run_queries} call. It is simply a sequentially
+    # increasing 0-based integer, ie. first call will return 0, second
+    # will return 1, and so on. Just a small helper so you won't have
+    # to track the indexes manualy if you need then.
+    #
+    # @param [String] query a query string.
+    # @param [String] index an index name (or names).
+    # @param [String] comment a comment to be sent to the query log.
+    # @return [Integer] an index into an array of results that will
+    #   be returned from {#run_queries} call.
+    #
+    # @example
+    #   sphinx.add_query('some search text', '*', 'search page')
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-addquery Section 6.6.2, "AddQuery"
+    # @see #query
+    # @see #run_queries
+    #
+    def add_query(query, index = '*', comment = '')
       # build request
-  
+
       # mode and limits
       request = Request.new
       request.put_int @offset, @limit, @mode, @ranker, @sort
@@ -920,8 +1597,8 @@ module Sphinx
       # id64 range marker
       request.put_int 1
       # id64 range
-      request.put_int64 @min_id.to_i, @max_id.to_i 
-      
+      request.put_int64 @min_id.to_i, @max_id.to_i
+
       # filters
       request.put_int @filters.length
       @filters.each do |filter|
@@ -940,7 +1617,7 @@ module Sphinx
         end
         request.put_int filter['exclude'] ? 1 : 0
       end
-      
+
       # group-by clause, max-matches count, group-sort clause, cutoff count
       request.put_int @groupfunc
       request.put_string @groupby
@@ -948,7 +1625,7 @@ module Sphinx
       request.put_string @groupsort
       request.put_int @cutoff, @retrycount, @retrydelay
       request.put_string @groupdistinct
-      
+
       # anchor point
       if @anchor.empty?
         request.put_int 0
@@ -957,27 +1634,27 @@ module Sphinx
         request.put_string @anchor['attrlat'], @anchor['attrlong']
         request.put_float @anchor['lat'], @anchor['long']
       end
-      
+
       # per-index weights
       request.put_int @indexweights.length
       @indexweights.each do |idx, weight|
         request.put_string idx.to_s
         request.put_int weight
       end
-      
+
       # max query time
       request.put_int @maxquerytime
-      
+
       # per-field weights
       request.put_int @fieldweights.length
       @fieldweights.each do |field, weight|
         request.put_string field.to_s
         request.put_int weight
       end
-      
+
       # comment
       request.put_string comment
-      
+
       # attribute overrides
       request.put_int @overrides.length
       for entry in @overrides do
@@ -995,173 +1672,196 @@ module Sphinx
           end
         end
       end
-      
+
       # select-list
       request.put_string @select
-      
+
       # store request to requests array
       @reqs << request.to_s;
       return @reqs.length - 1
     end
-    
-    # Run queries batch.
-    #
-    # Returns an array of result sets on success.
-    # Returns false on network IO failure.
-    #
-    # Each result set in returned array is a hash which containts
-    # the same keys as the hash returned by <tt>Query</tt>, plus:
-    #
-    # * <tt>'error'</tt> -- search error for this query
-    # * <tt>'words'</tt> -- hash which maps query terms (stemmed!) to ( "docs", "hits" ) hash
-    #
-    def RunQueries
+    alias :AddQuery :add_query
+
+    # Connect to searchd, runs a batch of all queries added using
+    # {#add_query}, obtains and returns the result sets. Returns
+    # +false+ and sets {#last_error} message on general error
+    # (such as network I/O failure). Returns a plain array of
+    # result sets on success.
+    #
+    # Each result set in the returned array is exactly the same as
+    # the result set returned from {#query}.
+    #
+    # Note that the batch query request itself almost always succeds —
+    # unless there's a network error, blocking index rotation in
+    # progress, or another general failure which prevents the whole
+    # request from being processed.
+    #
+    # However individual queries within the batch might very well
+    # fail. In this case their respective result sets will contain
+    # non-empty "error" message, but no matches or query statistics.
+    # In the extreme case all queries within the batch could fail.
+    # There still will be no general error reported, because API
+    # was able to succesfully connect to searchd, submit the batch,
+    # and receive the results — but every result set will have a
+    # specific error message.
+    #
+    # @return [Array<Hash>] an +Array+ of +Hash+es which are exactly
+    #   the same as the result set returned from {#query}.
+    #
+    # @example
+    #   sphinx.add_query('some search text', '*', 'search page')
+    #   results = sphinx.run_queries
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-runqueries Section 6.6.3, "RunQueries"
+    # @see #add_query
+    #
+    def run_queries
       if @reqs.empty?
-        @error = 'No queries defined, issue AddQuery() first'
+        @error = 'No queries defined, issue add_query() first'
         return false
       end
 
-      req = @reqs.join('')
-      nreqs = @reqs.length
+      reqs, nreqs = @reqs.join(''), @reqs.length
       @reqs = []
-      response = perform_request(:search, req, nreqs)
-     
+      response = perform_request(:search, reqs, nreqs)
+
       # parse response
-      begin
-        results = []
-        ires = 0
-        while ires < nreqs
-          ires += 1
-          result = {}
-          
-          result['error'] = ''
-          result['warning'] = ''
-          
-          # extract status
-          status = result['status'] = response.get_int
-          if status != SEARCHD_OK
-            message = response.get_string
-            if status == SEARCHD_WARNING
-              result['warning'] = message
-            else
-              result['error'] = message
-              results << result
-              next
-            end
-          end
-      
-          # read schema
-          fields = []
-          attrs = {}
-          attrs_names_in_order = []
-          
-          nfields = response.get_int
-          while nfields > 0
-            nfields -= 1
-            fields << response.get_string
+      (1..nreqs).map do
+        result = { 'error' => '', 'warning' => '' }
+
+        # extract status
+        status = result['status'] = response.get_int
+        if status != SEARCHD_OK
+          message = response.get_string
+          if status == SEARCHD_WARNING
+            result['warning'] = message
+          else
+            result['error'] = message
+            next result
           end
-          result['fields'] = fields
-      
-          nattrs = response.get_int
-          while nattrs > 0
-            nattrs -= 1
-            attr = response.get_string
-            type = response.get_int
-            attrs[attr] = type
-            attrs_names_in_order << attr
+        end
+
+        # read schema
+        nfields = response.get_int
+        result['fields'] = (1..nfields).map { response.get_string }
+
+        attrs_names_in_order = []
+        nattrs = response.get_int
+        attrs = (1..nattrs).inject({}) do |hash, idx|
+          name, type = response.get_string, response.get_int
+          hash[name] = type
+          attrs_names_in_order << name
+          hash
+        end
+        result['attrs'] = attrs
+
+        # read match count
+        count, id64 = response.get_ints(2)
+
+        # read matches
+        result['matches'] = (1..count).map do
+          doc, weight = if id64 == 0
+            response.get_ints(2)
+          else
+            [response.get_int64, response.get_int]
           end
-          result['attrs'] = attrs
-          
-          # read match count
-          count = response.get_int
-          id64 = response.get_int
-          
-          # read matches
-          result['matches'] = []
-          while count > 0
-            count -= 1
-            
-            if id64 != 0
-              doc = response.get_int64
-              weight = response.get_int
-            else
-              doc, weight = response.get_ints(2)
-            end
-      
-            r = {} # This is a single result put in the result['matches'] array
-            r['id'] = doc
-            r['weight'] = weight
-            attrs_names_in_order.each do |a|
-              r['attrs'] ||= {}
-  
-              case attrs[a]
-                when SPH_ATTR_BIGINT
-                  # handle 64-bit ints
-                  r['attrs'][a] = response.get_int64
-                when SPH_ATTR_FLOAT
-                  # handle floats
-                  r['attrs'][a] = response.get_float
-                when SPH_ATTR_STRING
-                  r['attrs'][a] = response.get_string
+
+          # This is a single result put in the result['matches'] array
+          match = { 'id' => doc, 'weight' => weight } 
+          match['attrs'] = attrs_names_in_order.inject({}) do |hash, name|
+            hash[name] = case attrs[name]
+              when SPH_ATTR_BIGINT
+                # handle 64-bit ints
+                response.get_int64
+              when SPH_ATTR_FLOAT
+                # handle floats
+                response.get_float
+              when SPH_ATTR_STRING
+                response.get_string
+              else
+                # handle everything else as unsigned ints
+                val = response.get_int
+                if (attrs[name] & SPH_ATTR_MULTI) != 0
+                  (1..val).map { response.get_int }
                 else
-                  # handle everything else as unsigned ints
-                  val = response.get_int
-                  if (attrs[a] & SPH_ATTR_MULTI) != 0
-                    r['attrs'][a] = []
-                    1.upto(val) do
-                      r['attrs'][a] << response.get_int
-                    end
-                  else
-                    r['attrs'][a] = val
-                  end
-              end
+                  val
+                end
             end
-            result['matches'] << r
+            hash
           end
-          result['total'], result['total_found'], msecs, words = response.get_ints(4)
-          result['time'] = '%.3f' % (msecs / 1000.0)
-  
-          result['words'] = {}
-          while words > 0
-            words -= 1
-            word = response.get_string
-            docs, hits = response.get_ints(2)
-            result['words'][word] = { 'docs' => docs, 'hits' => hits }
-          end
-          
-          results << result
+          match
         end
-      #rescue EOFError
-      #  @error = 'incomplete reply'
-      #  raise SphinxResponseError, @error
+        result['total'], result['total_found'], msecs = response.get_ints(3)
+        result['time'] = '%.3f' % (msecs / 1000.0)
+
+        nwords = response.get_int
+        result['words'] = (1..nwords).inject({}) do |hash, idx|
+          word = response.get_string
+          docs, hits = response.get_ints(2)
+          hash[word] = { 'docs' => docs, 'hits' => hits }
+          hash
+        end
+
+        result
       end
-      
-      return results
     end
-  
-    # Connect to searchd server and generate exceprts from given documents.
-    #
-    # * <tt>docs</tt> -- an array of strings which represent the documents' contents
-    # * <tt>index</tt> -- a string specifiying the index which settings will be used
-    # for stemming, lexing and case folding
-    # * <tt>words</tt> -- a string which contains the words to highlight
-    # * <tt>opts</tt> is a hash which contains additional optional highlighting parameters.
-    # 
-    # You can use following parameters:
-    # * <tt>'before_match'</tt> -- a string to insert before a set of matching words, default is "<b>"
-    # * <tt>'after_match'</tt> -- a string to insert after a set of matching words, default is "<b>"
-    # * <tt>'chunk_separator'</tt> -- a string to insert between excerpts chunks, default is " ... "
-    # * <tt>'limit'</tt> -- max excerpt size in symbols (codepoints), default is 256
-    # * <tt>'around'</tt> -- how much words to highlight around each match, default is 5
-    # * <tt>'exact_phrase'</tt> -- whether to highlight exact phrase matches only, default is <tt>false</tt>
-    # * <tt>'single_passage'</tt> -- whether to extract single best passage only, default is false
-    # * <tt>'use_boundaries'</tt> -- whether to extract passages by phrase boundaries setup in tokenizer
-    # * <tt>'weight_order'</tt> -- whether to order best passages in document (default) or weight order
-    #
-    # Returns false on failure.
-    # Returns an array of string excerpts on success.
-    #
-    def BuildExcerpts(docs, index, words, opts = {})
+    alias :RunQueries :run_queries
+    
+    #=================================================================
+    # Additional functionality
+    #=================================================================
+
+    # Excerpts (snippets) builder function. Connects to searchd, asks
+    # it to generate excerpts (snippets) from given documents, and
+    # returns the results.
+    #
+    # +docs+ is a plain array of strings that carry the documents'
+    # contents. +index+ is an index name string. Different settings
+    # (such as charset, morphology, wordforms) from given index will
+    # be used. +words+ is a string that contains the keywords to
+    # highlight. They will be processed with respect to index settings.
+    # For instance, if English stemming is enabled in the index,
+    # "shoes" will be highlighted even if keyword is "shoe". Starting
+    # with version 0.9.9-rc1, keywords can contain wildcards, that
+    # work similarly to star-syntax available in queries.
+    #
+    # @param [Array<String>] docs an array of strings which represent
+    #   the documents' contents.
+    # @param [String] index an index which settings will be used for
+    #   stemming, lexing and case folding.
+    # @param [String] words a string which contains the words to highlight.
+    # @param [Hash] opts a +Hash+ which contains additional optional
+    #   highlighting parameters.
+    # @option opts [String] 'before_match' ("<b>") a string to insert before a
+    #   keyword match.
+    # @option opts [String] 'after_match' ("</b>") a string to insert after a
+    #   keyword match.
+    # @option opts [String] 'chunk_separator' (" ... ") a string to insert
+    #   between snippet chunks (passages).
+    # @option opts [Integer] 'limit' (256) maximum snippet size, in symbols
+    #   (codepoints).
+    # @option opts [Integer] 'around' (5) how many words to pick around
+    #   each matching keywords block.
+    # @option opts [Boolean] 'exact_phrase' (false) whether to highlight exact
+    #   query phrase matches only instead of individual keywords.
+    # @option opts [Boolean] 'single_passage' (false) whether to extract single
+    #   best passage only.
+    # @option opts [Boolean] 'use_boundaries' (false) whether to extract
+    #   passages by phrase boundaries setup in tokenizer.
+    # @option opts [Boolean] 'weight_order' (false) whether to sort the
+    #   extracted passages in order of relevance (decreasing weight),
+    #   or in order of appearance in the document (increasing position).
+    # @return [Array<String>, false] a plain array of strings with
+    #   excerpts (snippets) on success; otherwise, +false+.
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @example
+    #   sphinx.build_excerpts(['hello world', 'hello me'], 'idx', 'hello')
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-buildexcerpts Section 6.7.1, "BuildExcerpts"
+    #
+    def build_excerpts(docs, index, words, opts = {})
       raise ArgumentError, '"docs" argument must be Array'   unless docs.kind_of?(Array)
       raise ArgumentError, '"index" argument must be String' unless index.kind_of?(String) or index.kind_of?(Symbol)
       raise ArgumentError, '"words" argument must be String' unless words.kind_of?(String)
@@ -1182,9 +1882,9 @@ module Sphinx
       opts['use_boundaries']  ||= opts[:use_boundaries]  || false
       opts['weight_order']    ||= opts[:weight_order]    || false
       opts['query_mode']      ||= opts[:query_mode]      || false
-      
+
       # build request
-      
+
       # v.1.0 req
       flags = 1
       flags |= 2  if opts['exact_phrase']
@@ -1192,47 +1892,71 @@ module Sphinx
       flags |= 8  if opts['use_boundaries']
       flags |= 16 if opts['weight_order']
       flags |= 32 if opts['query_mode']
-      
+
       request = Request.new
       request.put_int 0, flags # mode=0, flags=1 (remove spaces)
       # req index
       request.put_string index.to_s
       # req words
       request.put_string words
-  
+
       # options
       request.put_string opts['before_match']
       request.put_string opts['after_match']
       request.put_string opts['chunk_separator']
       request.put_int opts['limit'].to_i, opts['around'].to_i
-      
+
       # documents
       request.put_int docs.size
       request.put_string(*docs)
-      
+
       response = perform_request(:excerpt, request)
-      
+
       # parse response
-      begin
-        res = []
-        docs.each do |doc|
-          res << response.get_string
-        end
-      rescue EOFError
-        @error = 'incomplete reply'
-        raise SphinxResponseError, @error
-      end
-      return res
+      docs.map { response.get_string }
     end
-    
-    # Connect to searchd server, and generate keyword list for a given query.
-    #
-    # Returns an array of words on success.
-    def BuildKeywords(query, index, hits)
+    alias :BuildExcerpts :build_excerpts
+
+    # Extracts keywords from query using tokenizer settings for given
+    # index, optionally with per-keyword occurrence statistics.
+    # Returns an array of hashes with per-keyword information.
+    #
+    # +query+ is a query to extract keywords from. +index+ is a name of
+    # the index to get tokenizing settings and keyword occurrence
+    # statistics from. +hits+ is a boolean flag that indicates whether
+    # keyword occurrence statistics are required.
+    #
+    # The result set consists of +Hash+es with the following keys and values:
+    #
+    # <tt>'tokenized'</tt>::
+    #   Tokenized keyword.
+    # <tt>'normalized'</tt>::
+    #   Normalized keyword.
+    # <tt>'docs'</tt>::
+    #   A number of documents where keyword is found (if +hits+ param is +true+).
+    # <tt>'hits'</tt>::
+    #   A number of keywords occurrences among all documents (if +hits+ param is +true+).
+    #
+    # @param [String] query a query string.
+    # @param [String] index an index to get tokenizing settings and
+    #   keyword occurrence statistics from.
+    # @param [Boolean] hits indicates whether keyword occurrence
+    #   statistics are required.
+    # @return [Array<Hash>] an +Array+ of +Hash+es in format specified
+    #   above.
+    #
+    # @raise [ArgumentError] Occurred when parameters are invalid.
+    #
+    # @example
+    #   keywords = sphinx.build_keywords("this.is.my query", "test1", false)
+    #
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-buildkeywords Section 6.7.3, "BuildKeywords"
+    #
+    def build_keywords(query, index, hits)
       raise ArgumentError, '"query" argument must be String' unless query.kind_of?(String)
       raise ArgumentError, '"index" argument must be String' unless index.kind_of?(String) or index.kind_of?(Symbol)
       raise ArgumentError, '"hits" argument must be Boolean' unless hits.kind_of?(TrueClass) or hits.kind_of?(FalseClass)
-      
+
       # build request
       request = Request.new
       # v.1.0 req
@@ -1241,53 +1965,79 @@ module Sphinx
       request.put_int hits ? 1 : 0
 
       response = perform_request(:keywords, request)
-      
+
       # parse response
-      begin
-        res = []
-        nwords = response.get_int
-        0.upto(nwords - 1) do |i|
-          tokenized = response.get_string
-          normalized = response.get_string
-          
-          entry = { 'tokenized' => tokenized, 'normalized' => normalized }
-          entry['docs'], entry['hits'] = response.get_ints(2) if hits
-          
-          res << entry
-        end
-      rescue EOFError
-        @error = 'incomplete reply'
-        raise SphinxResponseError, @error
+      nwords = response.get_int
+      (0...nwords).map do
+        tokenized = response.get_string
+        normalized = response.get_string
+
+        entry = { 'tokenized' => tokenized, 'normalized' => normalized }
+        entry['docs'], entry['hits'] = response.get_ints(2) if hits
+
+        entry
       end
-      
-      return res
     end
+    alias :BuildKeywords :build_keywords
 
-    # Batch update given attributes in given rows in given indexes.
+    # Instantly updates given attribute values in given documents.
+    # Returns number of actually updated documents (0 or more) on
+    # success, or -1 on failure.
+    # 
+    # +index+ is a name of the index (or indexes) to be updated.
+    # +attrs+ is a plain array with string attribute names, listing
+    # attributes that are updated. +values+ is a Hash where key is
+    # document ID, and value is a plain array of new attribute values.
+    # 
+    # +index+ can be either a single index name or a list, like in
+    # {#query}. Unlike {#query}, wildcard is not allowed and all the
+    # indexes to update must be specified explicitly. The list of
+    # indexes can include distributed index names. Updates on
+    # distributed indexes will be pushed to all agents.
+    # 
+    # The updates only work with docinfo=extern storage strategy.
+    # They are very fast because they're working fully in RAM, but
+    # they can also be made persistent: updates are saved on disk
+    # on clean searchd shutdown initiated by SIGTERM signal. With
+    # additional restrictions, updates are also possible on MVA
+    # attributes; refer to mva_updates_pool directive for details.
+    #
+    # The first sample statement will update document 1 in index
+    # "test1", setting "group_id" to 456. The second one will update
+    # documents 1001, 1002 and 1003 in index "products". For document
+    # 1001, the new price will be set to 123 and the new amount in
+    # stock to 5; for document 1002, the new price will be 37 and the
+    # new amount will be 11; etc. The third one updates document 1
+    # in index "test2", setting MVA attribute "group_id" to [456, 789].
+    # 
+    # @example
+    #   sphinx.update_attributes("test1", ["group_id"], { 1 => [456] });
+    #   sphinx.update_attributes("products", ["price", "amount_in_stock"],
+    #     { 1001 => [123, 5], 1002 => [37, 11], 1003 => [25, 129] });
+    #   sphinx.update_attributes('test2', ['group_id'], { 1 => [[456, 789]] }, true)
     #
-    # * +index+ is a name of the index to be updated
-    # * +attrs+ is an array of attribute name strings.
-    # * +values+ is a hash where key is document id, and value is an array of
-    # * +mva+ identifies whether update MVA
-    # new attribute values
+    # @param [String] index a name of the index to be updated.
+    # @param [Array<String>] attrs an array of attribute name strings.
+    # @param [Hash] values is a hash where key is document id, and
+    #   value is an array of new attribute values.
+    # @param [Boolean] mva indicating whether to update MVA.
+    # @return [Integer] number of actually updated documents (0 or more) on success,
+    #   -1 on failure.
     #
-    # Returns number of actually updated documents (0 or more) on success.
-    # Returns -1 on failure.
+    # @raise [ArgumentError] Occurred when parameters are invalid.
     #
-    # Usage example:
-    #    sphinx.UpdateAttributes('test1', ['group_id'], { 1 => [456] })
-    #    sphinx.UpdateAttributes('test1', ['group_id'], { 1 => [[456, 789]] }, true)
+    # @see http://www.sphinxsearch.com/docs/current.html#api-func-updateatttributes Section 6.7.2, "UpdateAttributes"
     #
-    def UpdateAttributes(index, attrs, values, mva = false)
+    def update_attributes(index, attrs, values, mva = false)
       # verify everything
       raise ArgumentError, '"index" argument must be String' unless index.kind_of?(String) or index.kind_of?(Symbol)
       raise ArgumentError, '"mva" argument must be Boolean'  unless mva.kind_of?(TrueClass) or mva.kind_of?(FalseClass)
-      
+
       raise ArgumentError, '"attrs" argument must be Array' unless attrs.kind_of?(Array)
       attrs.each do |attr|
         raise ArgumentError, '"attrs" argument must be Array of Strings' unless attr.kind_of?(String) or attr.kind_of?(Symbol)
       end
-      
+
       raise ArgumentError, '"values" argument must be Hash' unless values.kind_of?(Hash)
       values.each do |id, entry|
         raise ArgumentError, '"values" argument must be Hash map of Integer to Array' unless id.respond_to?(:integer?) and id.integer?
@@ -1304,17 +2054,17 @@ module Sphinx
           end
         end
       end
-      
+
       # build request
       request = Request.new
       request.put_string index
-      
+
       request.put_int attrs.length
       for attr in attrs
         request.put_string attr
         request.put_int mva ? 1 : 0
       end
-      
+
       request.put_int values.length
       values.each do |id, entry|
         request.put_int64 id
@@ -1324,33 +2074,89 @@ module Sphinx
           request.put_int(*entry)
         end
       end
-      
+
       response = perform_request(:update, request)
-      
+
+      # parse response
+      response.get_int
+    end
+    alias :UpdateAttributes :update_attributes
+
+    # Queries searchd status, and returns an array of status variable name
+    # and value pairs.
+    #
+    # @return [Array<Array>] a table containing searchd status information.
+    #
+    # @example
+    #   status = sphinx.status
+    #   puts status.map { |key, value| "#{key.rjust(20)}: #{value}" }
+    #
+    def status
+      request = Request.new
+      request.put_int(1)
+      response = perform_request(:status, request)
+
+      # parse response
+      rows, cols = response.get_ints(2)
+      (0...rows).map do
+        (0...cols).map { response.get_string }
+      end
+    end
+    alias :Status :status
+
+    # Force attribute flush, and block until it completes.
+    #
+    # @return [Integer] current internal flush tag on success, -1 on failure.
+    #
+    # @example
+    #   sphinx.flush_attrs
+    #
+    def flush_attrs
+      request = Request.new
+      response = perform_request(:flushattrs, request)
+
       # parse response
       begin
-        return response.get_int
+        response.get_int
       rescue EOFError
-        @error = 'incomplete reply'
-        raise SphinxResponseError, @error
+        -1
       end
     end
-    
-    # persistent connections
-    
+    alias :FlushAttrs :flush_attrs
+
+    #=================================================================
+    # Persistent connections
+    #=================================================================
+
     # Opens persistent connection to the server.
     #
-    def Open
+    # This method could be used only when a single searchd server
+    # configured.
+    #
+    # @return [Boolean] +true+ when persistent connection has been
+    #   established; otherwise, +false+.
+    #
+    # @example
+    #   begin
+    #     sphinx.open
+    #     # perform several requests
+    #   ensure
+    #     sphinx.close
+    #   end
+    #
+    # @see #close
+    #
+    def open
       if @servers.size > 1
         @error = 'too many servers. persistent socket allowed only for a single server.'
         return false
       end
-      
+
       if @servers.first.persistent?
         @error = 'already connected'
         return false;
       end
-      
+
       request = Request.new
       request.put_int(1)
 
@@ -1360,85 +2166,64 @@ module Sphinx
 
       true
     end
-    
+    alias :Open :open
+
     # Closes previously opened persistent connection.
     #
-    def Close
+    # This method could be used only when a single searchd server
+    # configured.
+    #
+    # @return [Boolean] +true+ when persistent connection has been
+    #   closed; otherwise, +false+.
+    #
+    # @example
+    #   begin
+    #     sphinx.open
+    #     # perform several requests
+    #   ensure
+    #     sphinx.close
+    #   end
+    #
+    # @see #open
+    #
+    def close
       if @servers.size > 1
         @error = 'too many servers. persistent socket allowed only for a single server.'
         return false
       end
-      
+
       unless @servers.first.persistent?
         @error = 'not connected'
         return false;
       end
-      
-      @servers.first.close_persistent!
-    end
-    
-    # Queries searchd status, and returns an array of status variable name
-    # and value pairs.
-    #
-    # Usage example:
-    #
-    #   status = sphinx.Status
-    #   puts status.map { |key, value| "#{key.rjust(20)}: #{value}" }
-    #
-    def Status
-      request = Request.new
-      request.put_int(1)
-      response = perform_request(:status, request)
 
-      # parse response
-      begin
-        rows, cols = response.get_ints(2)
-      
-        res = []
-        0.upto(rows - 1) do |i|
-          res[i] = []
-          0.upto(cols - 1) do |j|
-            res[i] << response.get_string
-          end
-        end
-      rescue EOFError
-        @error = 'incomplete reply'
-        raise SphinxResponseError, @error
-      end
-      
-      res
+      @servers.first.close_persistent!
     end
-    
-    def FlushAttrs
-      request = Request.new
-      response = perform_request(:flushattrs, request)
+    alias :Close :close
 
-      # parse response
-      begin
-        response.get_int
-      rescue EOFError
-        -1
-      end
-    end
-  
     protected
-      
+
       # Connect, send query, get response.
       #
       # Use this method to communicate with Sphinx server. It ensures connection
       # will be instantiated properly, all headers will be generated properly, etc.
       #
-      # Parameters:
-      # * +command+ -- searchd command to perform (<tt>:search</tt>, <tt>:excerpt</tt>,
+      # @param [Symbol, String] command searchd command to perform (<tt>:search</tt>, <tt>:excerpt</tt>,
       #   <tt>:update</tt>, <tt>:keywords</tt>, <tt>:persist</tt>, <tt>:status</tt>,
       #   <tt>:query</tt>, <tt>:flushattrs</tt>. See <tt>SEARCHD_COMMAND_*</tt> for details).
-      # * +request+ -- an instance of <tt>Sphinx::Request</tt> class. Contains request body.
-      # * +additional+ -- additional integer data to be placed between header and body.
-      # * +block+ -- if given, response will not be parsed, plain socket will be
-      #   passed instead. this is special mode used for persistent connections,
-      #   do not use for other tasks.
+      # @param [Sphinx::Request] request contains request body.
+      # @param [nil, Integer] additional additional integer data to be placed between header and body.
+      #
+      # @yield if block given, response will not be parsed, plain socket
+      #   will be yielded instead. This is special mode used for
+      #   persistent connections, do not use for other tasks.
+      # @yieldparam [Sphinx::Server] server a server where request was performed on.
+      # @yieldparam [Sphinx::BufferedIO] socket a socket used to perform the request.
+      # @return [Sphinx::Response] contains response body.
       #
-      def perform_request(command, request, additional = nil, &block)
+      # @see #parse_response
+      #
+      def perform_request(command, request, additional = nil)
         with_server do |server|
           cmd = command.to_s.upcase
           command_id = Sphinx::Client.const_get("SEARCHD_COMMAND_#{cmd}")
@@ -1465,26 +2250,31 @@ module Sphinx
       #
       # There are several exceptions which could be thrown in this method:
       #
-      # * various network errors -- should be handled by caller (see +with_socket+).
-      # * +SphinxResponseError+ -- incomplete reply from searchd.
-      # * +SphinxInternalError+ -- searchd error.
-      # * +SphinxTemporaryError+ -- temporary searchd error.
-      # * +SphinxUnknownError+ -- unknows searchd error.
+      # @param [Sphinx::BufferedIO] socket an input stream object.
+      # @param [Integer] client_version a command version which client supports.
+      # @return [Sphinx::Response] could be used for context-based
+      #   parsing of reply from the server.
+      #
+      # @raise [SystemCallError, SocketError] should be handled by caller (see {#with_socket}).
+      # @raise [SphinxResponseError] incomplete reply from searchd.
+      # @raise [SphinxInternalError] searchd internal error.
+      # @raise [SphinxTemporaryError] searchd temporary error.
+      # @raise [SphinxUnknownError] searchd unknown error.
       #
-      # Method returns an instance of <tt>Sphinx::Response</tt> class, which
-      # could be used for context-based parsing of reply from the server.
+      # @see #with_socket
+      # @private
       #
       def parse_response(socket, client_version)
         response = ''
         status = ver = len = 0
-        
-        # Read server reply from server. All exceptions are handled by +with_socket+.
+
+        # Read server reply from server. All exceptions are handled by {#with_socket}.
         header = socket.read(8)
         if header.length == 8
           status, ver, len = header.unpack('n2N')
           response = socket.read(len) if len > 0
         end
-    
+
         # check response
         read = response.length
         if response.empty? or read != len.to_i
@@ -1493,7 +2283,7 @@ module Sphinx
             : 'received zero-sized searchd response'
           raise SphinxResponseError, error
         end
-        
+
         # check status
         if (status == SEARCHD_WARNING)
           wlen = response[0, 4].unpack('N*').first
@@ -1505,34 +2295,40 @@ module Sphinx
           error = 'searchd error: ' + response[4, response.length - 4]
           raise SphinxInternalError, error
         end
-    
+
         if status == SEARCHD_RETRY
           error = 'temporary searchd error: ' + response[4, response.length - 4]
           raise SphinxTemporaryError, error
         end
-    
+
         unless status == SEARCHD_OK
           error = "unknown status code: '#{status}'"
           raise SphinxUnknownError, error
         end
-        
+
         # check version
         if ver < client_version
           @warning = "searchd command v.#{ver >> 8}.#{ver & 0xff} older than client's " +
             "v.#{client_version >> 8}.#{client_version & 0xff}, some options might not work"
         end
-        
+
         Response.new(response)
       end
-      
+
       # This is internal method which selects next server (round-robin)
       # and yields it to the block passed.
       #
       # In case of connection error, it will try next server several times
-      # (see +SetConnectionTimeout+ method details). If all servers are down,
-      # it will set +error+ attribute value with the last exception message,
-      # and <tt>connection_timeout?</tt> method will return true. Also,
-      # +SphinxConnectErorr+ exception will be raised.
+      # (see {#set_connect_timeout} method details). If all servers are down,
+      # it will set error attribute (could be retrieved with {#last_error}
+      # method) with the last exception message, and {#connect_error?}
+      # method will return true. Also, {SphinxConnectError} exception
+      # will be raised.
+      #
+      # @yield a block which performs request on a given server.
+      # @yieldparam [Sphinx::Server] server contains information
+      #   about the server to perform request on.
+      # @raise [SphinxConnectError] on any connection error.
       #
       def with_server
         attempts = @retries
@@ -1552,29 +2348,39 @@ module Sphinx
           raise
         end
       end
-      
+
       # This is internal method which retrieves socket for a given server,
       # initiates Sphinx session, and yields this socket to a block passed.
       #
-      # In case of any problems with session initiation, +SphinxConnectError+
+      # In case of any problems with session initiation, {SphinxConnectError}
       # will be raised, because this is part of connection establishing. See
-      # +with_server+ method details to get more infromation about how this
+      # {#with_server} method details to get more infromation about how this
       # exception is handled.
       #
       # Socket retrieving routine is wrapped in a block with it's own
-      # timeout value (see +SetConnectTimeout+). This is done in
-      # <tt>Server#get_socket</tt> method, so check it for details.
+      # timeout value (see {#set_connect_timeout}). This is done in
+      # {Server#get_socket} method, so check it for details.
       #
       # Request execution is wrapped with block with another timeout
-      # (see +SetRequestTimeout+). This ensures no Sphinx request will
+      # (see {#set_request_timeout}). This ensures no Sphinx request will
       # take unreasonable time.
       #
       # In case of any Sphinx error (incomplete reply, internal or temporary
       # error), connection to the server will be re-established, and request
-      # will be retried (see +SetRequestTimeout+). Of course, if connection
+      # will be retried (see {#set_request_timeout}). Of course, if connection
       # could not be established, next server will be selected (see explanation
       # above).
       #
+      # @param [Sphinx::Server] server contains information
+      #   about the server to perform request on.
+      # @yield a block which will actually perform the request.
+      # @yieldparam [Sphinx::BufferedIO] socket a socket used to
+      #   perform the request.
+      #
+      # @raise [SphinxResponseError, SphinxInternalError, SphinxTemporaryError, SphinxUnknownError]
+      #   on any response error.
+      # @raise [SphinxConnectError] on any connection error.
+      #
       def with_socket(server)
         attempts = @reqretries
         socket = nil
@@ -1612,14 +2418,14 @@ module Sphinx
             new_e.set_backtrace(e.backtrace)
             e = new_e
           end
-        
+
           # Close previously opened socket (in case of it has been really opened)
           server.free_socket(socket)
 
           # Request error! Do we need to try it again?
           attempts -= 1
           retry if attempts > 0
-        
+
           # Re-raise original exception
           @error = e.message
           raise e