chewy 0.10.1 → 5.0.0

data/lib/chewy/minitest/helpers.rb

@@ -6,14 +6,14 @@ module Chewy
       extend ActiveSupport::Concern
 
       # Assert that an index *changes* during a block.
-      # @param (Chewy::Type) index the index / type to watch, eg EntitiesIndex::Entity.
-      # @param (Symbol) strategy the Chewy strategy to use around the block. See Chewy docs.
-      # @param (boolean) assert the index changes
-      # @param (boolean) bypass_actual_index
+      # @param index [Chewy::Type] the index / type to watch, eg EntitiesIndex::Entity.
+      # @param strategy [Symbol] the Chewy strategy to use around the block. See Chewy docs.
+      # @param bypass_actual_index [true, false]
       #   True to preempt the http call to Elastic, false otherwise.
       #   Should be set to true unless actually testing search functionality.
       #
-      # @return (SearchIndexReceiver) for optional further assertions on the nature of the index changes.
+      # @return [SearchIndexReceiver] for optional further assertions on the nature of the index changes.
+      #
       def assert_indexes(index, strategy: :atomic, bypass_actual_index: true)
         type = Chewy.derive_type index
         receiver = SearchIndexReceiver.new
@@ -43,7 +43,7 @@ module Chewy
 
       # Run indexing for the database changes during the block provided.
       # By default, indexing is run at the end of the block.
-      # @param (Symbol) strategy the Chewy index update strategy see Chewy docs.
+      # @param strategy [Symbol] the Chewy index update strategy see Chewy docs.
       def run_indexing(strategy: :atomic)
         Chewy.strategy strategy do
           yield

data/lib/chewy/minitest/search_index_receiver.rb

@@ -1,17 +1,17 @@
 # Test helper class to provide minitest hooks for Chewy::Index testing.
 #
 # @note Intended to be used in conjunction with a test helper which mocks over the #bulk
-#   method on a Chewy::Type class. (See SearchTestHelper)
+#   method on a {Chewy::Type} class. (See SearchTestHelper)
 #
-# The class will capture the data from the *param on the Chewy::Type#bulk method and
+# The class will capture the data from the *param on the Chewy::Type.bulk method and
 # aggregate the data for test analysis.
 class SearchIndexReceiver
   def initialize
     @mutations = {}
   end
 
-  # @param bulk_params the bulk_params that should be sent to the Chewy::Type#bulk method.
-  # @param (Chewy::Type) type the Index::Type executing this query.
+  # @param bulk_params [Hash] the bulk_params that should be sent to the Chewy::Type.bulk method.
+  # @param type [Chewy::Type] the type executing this query.
   def catch(bulk_params, type)
     Array.wrap(bulk_params).map { |y| y[:body] }.flatten.each do |update|
       if update[:delete]
@@ -22,8 +22,8 @@ class SearchIndexReceiver
     end
   end
 
-  # @param index return only index requests to the specified Chewy::Type index.
-  # @return the index changes captured by the mock.
+  # @param index [Chewy::Index] return only index requests to the specified {Chewy::Type} index.
+  # @return [Hash] the index changes captured by the mock.
   def indexes_for(index = nil)
     if index
       mutation_for(index).indexes
@@ -35,8 +35,8 @@ class SearchIndexReceiver
   end
   alias_method :indexes, :indexes_for
 
-  # @param index return only delete requests to the specified Chewy::Type index.
-  # @return the index deletes captured by the mock.
+  # @param index [Chewy::Index] return only delete requests to the specified {Chewy::Type} index.
+  # @return [Hash] the index deletes captured by the mock.
   def deletes_for(index = nil)
     if index
       mutation_for(index).deletes
@@ -49,22 +49,22 @@ class SearchIndexReceiver
   alias_method :deletes, :deletes_for
 
   # Check to see if a given object has been indexed.
-  # @param (#id) obj the object to look for.
-  # @param Chewy::Type what type the object should be indexed as.
-  # @return bool if the object was indexed.
+  # @param obj [#id] obj the object to look for.
+  # @param type [Chewy::Type] what type the object should be indexed as.
+  # @return [true, false] if the object was indexed.
   def indexed?(obj, type)
     indexes_for(type).map { |i| i[:_id] }.include? obj.id
   end
 
   # Check to see if a given object has been deleted.
-  # @param (#id) obj the object to look for.
-  # @param Chewy::Type what type the object should have been deleted from.
-  # @return bool if the object was deleted.
+  # @param obj [#id] obj the object to look for.
+  # @param type [Chewy::Type] what type the object should have been deleted from.
+  # @return [true, false] if the object was deleted.
   def deleted?(obj, type)
     deletes_for(type).include? obj.id
   end
 
-  # @return a list of Chewy::Type indexes changed.
+  # @return [Array<Chewy::Type>] a list of types indexes changed.
   def updated_indexes
     @mutations.keys
   end
@@ -72,8 +72,8 @@ class SearchIndexReceiver
 private
 
   # Get the mutation object for a given type.
-  # @param (Chewy::Type) type the index type to fetch.
-  # @return (#indexes, #deletes) an object with a list of indexes and a list of deletes.
+  # @param type [Chewy::Type] the index type to fetch.
+  # @return [#indexes, #deletes] an object with a list of indexes and a list of deletes.
   def mutation_for(type)
     @mutations[type] ||= OpenStruct.new(indexes: [], deletes: [])
   end

data/lib/chewy/query.rb

@@ -8,6 +8,7 @@ module Chewy
   # chainable DSL. Queries are lazy evaluated and might be merged.
   # The same DSL is used for whole index or individual types query build.
   #
+  # @example
   #   UsersIndex.filter{ age < 42 }.query(text: {name: 'Alex'}).limit(20)
   #   UsersIndex::User.filter{ age < 42 }.query(text: {name: 'Alex'}).limit(20)
   #
@@ -43,6 +44,7 @@ module Chewy
     # If other is collection - search request is executed and
     # result is used for comparation
     #
+    # @example
     #   UsersIndex.filter(term: {name: 'Johny'}) == UsersIndex.filter(term: {name: 'Johny'}) # => true
     #   UsersIndex.filter(term: {name: 'Johny'}) == UsersIndex.filter(term: {name: 'Johny'}).to_a # => true
     #   UsersIndex.filter(term: {name: 'Johny'}) == UsersIndex.filter(term: {name: 'Winnie'}) # => false
@@ -51,23 +53,27 @@ module Chewy
       super || other.is_a?(self.class) ? other.criteria == criteria : other == to_a
     end
 
-    # Adds <tt>explain</tt> parameter to search request.
+    # Adds `explain` parameter to search request.
     #
+    # @example
     #   UsersIndex.filter(term: {name: 'Johny'}).explain
     #   UsersIndex.filter(term: {name: 'Johny'}).explain(true)
     #   UsersIndex.filter(term: {name: 'Johny'}).explain(false)
     #
     # Calling explain without any arguments sets explanation flag to true.
-    # With <tt>explain: true</tt>, every result object has <tt>_explanation</tt>
+    # With `explain: true`, every result object has `_explanation`
     # method
     #
+    # @example
     #   UsersIndex::User.filter(term: {name: 'Johny'}).explain.first._explanation # => {...}
     #
     def explain(value = nil)
       chain { criteria.update_request_options explain: (value.nil? ? true : value) }
     end
 
-    # Adds <tt>script_fields</tt> parameter to search request.
+    # Adds `script_fields` parameter to search request.
+    #
+    # @example
     #  UsersIndex.script_fields(
     #    distance: {
     #      params: {
@@ -85,31 +91,28 @@ module Chewy
     # Not used if only one filter for search is specified.
     # Possible values:
     #
-    # * <tt>:must</tt>
-    #   Default value. Query compiles into a bool <tt>must</tt> query.
-    #
-    #   Ex:
+    # * `:must`
+    #   Default value. Query compiles into a bool `must` query.
     #
+    # @example
     #     UsersIndex.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}})
     #       # => {body: {
     #              query: {bool: {must: [{text: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}}
     #            }}
     #
-    # * <tt>:should</tt>
-    #   Query compiles into a bool <tt>should</tt> query.
-    #
-    #   Ex:
+    # * `:should`
+    #   Query compiles into a bool `should` query.
     #
+    # @example
     #     UsersIndex.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}}).query_mode(:should)
     #       # => {body: {
     #              query: {bool: {should: [{text: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}}
     #            }}
     #
-    # * Any acceptable <tt>minimum_should_match</tt> value (1, '2', '75%')
-    #   Query compiles into a bool <tt>should</tt> query with <tt>minimum_should_match</tt> set.
-    #
-    #   Ex:
+    # * Any acceptable `minimum_should_match` value (1, '2', '75%')
+    #   Query compiles into a bool `should` query with `minimum_should_match` set.
     #
+    # @example
     #     UsersIndex.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}}).query_mode('50%')
     #       # => {body: {
     #              query: {bool: {
@@ -118,21 +121,19 @@ module Chewy
     #              }}
     #            }}
     #
-    # * <tt>:dis_max</tt>
-    #   Query compiles into a <tt>dis_max</tt> query.
-    #
-    #   Ex:
+    # * `:dis_max`
+    #   Query compiles into a `dis_max` query.
     #
+    # @example
     #     UsersIndex.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}}).query_mode(:dis_max)
     #       # => {body: {
     #              query: {dis_max: {queries: [{text: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}}
     #            }}
     #
     # * Any Float value (0.0, 0.7, 1.0)
-    #   Query compiles into a <tt>dis_max</tt> query with <tt>tie_breaker</tt> option set.
-    #
-    #   Ex:
+    #   Query compiles into a `dis_max` query with `tie_breaker` option set.
     #
+    # @example
     #     UsersIndex.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}}).query_mode(0.7)
     #       # => {body: {
     #              query: {dis_max: {
@@ -141,9 +142,10 @@ module Chewy
     #              }}
     #            }}
     #
-    # Default value for <tt>:query_mode</tt> might be changed
-    # with <tt>Chewy.query_mode</tt> config option.
+    # Default value for `:query_mode` might be changed
+    # with `Chewy.query_mode` config option.
     #
+    # @example
     #   Chewy.query_mode = :dis_max
     #   Chewy.query_mode = '50%'
     #
@@ -155,55 +157,50 @@ module Chewy
     # Not used if only one filter for search is specified.
     # Possible values:
     #
-    # * <tt>:and</tt>
-    #   Default value. Filter compiles into an <tt>and</tt> filter.
-    #
-    #   Ex:
+    # * `:and`
+    #   Default value. Filter compiles into an `and` filter.
     #
+    # @example
     #     UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }
     #       # => {body: {query: {filtered: {
     #              query: {...},
     #              filter: {and: [{term: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}
     #            }}}}
     #
-    # * <tt>:or</tt>
-    #   Filter compiles into an <tt>or</tt> filter.
-    #
-    #   Ex:
+    # * `:or`
+    #   Filter compiles into an `or` filter.
     #
+    # @example
     #     UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }.filter_mode(:or)
     #       # => {body: {query: {filtered: {
     #              query: {...},
     #              filter: {or: [{term: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}
     #            }}}}
     #
-    # * <tt>:must</tt>
-    #   Filter compiles into a bool <tt>must</tt> filter.
-    #
-    #   Ex:
+    # * `:must`
+    #   Filter compiles into a bool `must` filter.
     #
+    # @example
     #     UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }.filter_mode(:must)
     #       # => {body: {query: {filtered: {
     #              query: {...},
     #              filter: {bool: {must: [{term: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}}
     #            }}}}
     #
-    # * <tt>:should</tt>
-    #   Filter compiles into a bool <tt>should</tt> filter.
-    #
-    #   Ex:
+    # * `:should`
+    #   Filter compiles into a bool `should` filter.
     #
+    # @example
     #     UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }.filter_mode(:should)
     #       # => {body: {query: {filtered: {
     #              query: {...},
     #              filter: {bool: {should: [{term: {name: 'Johny'}}, {range: {age: {lte: 42}}}]}}
     #            }}}}
     #
-    # * Any acceptable <tt>minimum_should_match</tt> value (1, '2', '75%')
-    #   Filter compiles into bool <tt>should</tt> filter with <tt>minimum_should_match</tt> set.
-    #
-    #   Ex:
+    # * Any acceptable `minimum_should_match` value (1, '2', '75%')
+    #   Filter compiles into bool `should` filter with `minimum_should_match` set.
     #
+    # @example
     #     UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }.filter_mode('50%')
     #       # => {body: {query: {filtered: {
     #              query: {...},
@@ -213,9 +210,10 @@ module Chewy
     #              }}
     #            }}}}
     #
-    # Default value for <tt>:filter_mode</tt> might be changed
-    # with <tt>Chewy.filter_mode</tt> config option.
+    # Default value for `:filter_mode` might be changed
+    # with `Chewy.filter_mode` config option.
     #
+    # @example
     #   Chewy.filter_mode = :should
     #   Chewy.filter_mode = '50%'
     #
@@ -227,6 +225,7 @@ module Chewy
     # Note that it fallbacks by default to `Chewy.filter_mode` if
     # `Chewy.post_filter_mode` is nil.
     #
+    # @example
     #   UsersIndex.post_filter{ name == 'Johny' }.post_filter{ age <= 42 }.post_filter_mode(:and)
     #   UsersIndex.post_filter{ name == 'Johny' }.post_filter{ age <= 42 }.post_filter_mode(:should)
     #   UsersIndex.post_filter{ name == 'Johny' }.post_filter{ age <= 42 }.post_filter_mode('50%')
@@ -250,6 +249,7 @@ module Chewy
     # The response to a search request will indicate whether the search timed
     # out and how many shards responded successfully:
     #
+    # @example
     #   ...
     #   "timed_out":     true,
     #   "_shards": {
@@ -267,6 +267,7 @@ module Chewy
     # responding with an error. The timeout parameter can be used to explicitly
     # specify how long it waits.
     #
+    # @example
     #   UsersIndex.timeout("5000ms")
     #
     # Timeout is not a circuit breaker.
@@ -284,9 +285,10 @@ module Chewy
       chain { criteria.update_request_options timeout: value }
     end
 
-    # Sets elasticsearch <tt>size</tt> search request param
+    # Sets elasticsearch `size` search request param
     # Default value is set in the elasticsearch and is 10.
     #
+    # @example
     #  UsersIndex.filter{ name == 'Johny' }.limit(100)
     #     # => {body: {
     #            query: {...},
@@ -297,8 +299,9 @@ module Chewy
       chain { criteria.update_request_options size: block || Integer(value) }
     end
 
-    # Sets elasticsearch <tt>from</tt> search request param
+    # Sets elasticsearch `from` search request param
     #
+    # @example
     #  UsersIndex.filter{ name == 'Johny' }.offset(300)
     #     # => {body: {
     #            query: {...},
@@ -311,6 +314,7 @@ module Chewy
 
     # Elasticsearch highlight query option support
     #
+    # @example
     #   UsersIndex.query(...).highlight(fields: { ... })
     #
     def highlight(value)
@@ -319,6 +323,7 @@ module Chewy
 
     # Elasticsearch rescore query option support
     #
+    # @example
     #   UsersIndex.query(...).rescore(query: { ... })
     #
     def rescore(value)
@@ -327,7 +332,8 @@ module Chewy
 
     # Elasticsearch minscore option support
     #
-    # UsersIndex.query(...).min_score(0.5)
+    # @example
+    #   UsersIndex.query(...).min_score(0.5)
     #
     def min_score(value)
       chain { criteria.update_request_options min_score: value }
@@ -335,7 +341,8 @@ module Chewy
 
     # Elasticsearch track_scores option support
     #
-    # UsersIndex.query(...).track_scores(true)
+    # @example
+    #   UsersIndex.query(...).track_scores(true)
     #
     def track_scores(value)
       chain { criteria.update_request_options track_scores: value }
@@ -345,6 +352,7 @@ module Chewy
     # All the chained facets a merged and added to the
     # search request
     #
+    # @example
     #   UsersIndex.facets(tags: {terms: {field: 'tags'}}).facets(ages: {terms: {field: 'age'}})
     #     # => {body: {
     #            query: {...},
@@ -365,8 +373,9 @@ module Chewy
 
     # Adds a script function to score the search request. All scores are
     # added to the search request and combinded according to
-    # <tt>boost_mode</tt> and <tt>score_mode</tt>
+    # `boost_mode` and `score_mode`
     #
+    # @example
     #   UsersIndex.script_score("doc['boost'].value", params: { modifier: 2 })
     #       # => {body:
     #              query: {
@@ -387,11 +396,12 @@ module Chewy
 
     # Adds a boost factor to the search request. All scores are
     # added to the search request and combinded according to
-    # <tt>boost_mode</tt> and <tt>score_mode</tt>
+    # `boost_mode` and `score_mode`
     #
     # This probably only makes sense if you specify a filter
     # for the boost factor as well
     #
+    # @example
     #   UsersIndex.boost_factor(23, filter: { term: { foo: :bar} })
     #       # => {body:
     #              query: {
@@ -409,11 +419,12 @@ module Chewy
 
     # Add a weight scoring function to the search. All scores are
     # added to the search request and combinded according to
-    # <tt>boost_mode</tt> and <tt>score_mode</tt>
+    # `boost_mode` and `score_mode`
     #
     # This probably only makes sense if you specify a filter
     # for the weight as well.
     #
+    # @example
     #   UsersIndex.weight(23, filter: { term: { foo: :bar} })
     #       # => {body:
     #              query: {
@@ -431,13 +442,14 @@ module Chewy
 
     # Adds a random score to the search request. All scores are
     # added to the search request and combinded according to
-    # <tt>boost_mode</tt> and <tt>score_mode</tt>
+    # `boost_mode` and `score_mode`
     #
     # This probably only makes sense if you specify a filter
     # for the random score as well.
     #
     # If you do not pass in a seed value, Time.now will be used
     #
+    # @example
     #   UsersIndex.random_score(23, filter: { foo: :bar})
     #       # => {body:
     #              query: {
@@ -455,11 +467,12 @@ module Chewy
 
     # Add a field value scoring to the search. All scores are
     # added to the search request and combinded according to
-    # <tt>boost_mode</tt> and <tt>score_mode</tt>
+    # `boost_mode` and `score_mode`
     #
     # This function is only available in Elasticsearch 1.2 and
     # greater
     #
+    # @example
     #   UsersIndex.field_value_factor(
     #                {
     #                  field: :boost,
@@ -486,11 +499,12 @@ module Chewy
 
     # Add a decay scoring to the search. All scores are
     # added to the search request and combinded according to
-    # <tt>boost_mode</tt> and <tt>score_mode</tt>
+    # `boost_mode` and `score_mode`
     #
     # The parameters have default values, but those may not
     # be very useful for most applications.
     #
+    # @example
     #   UsersIndex.decay(
     #                :gauss,
     #                :field,
@@ -523,17 +537,19 @@ module Chewy
       chain { criteria.update_scores scoring }
     end
 
-    # Sets <tt>preference</tt> for request.
-    # For instance, one can use <tt>preference=_primary</tt> to execute only on the primary shards.
+    # Sets `preference` for request.
+    # For instance, one can use `preference=_primary` to execute only on the primary shards.
     #
+    # @example
     #   scope = UsersIndex.preference(:_primary)
     #
     def preference(value)
       chain { criteria.update_search_options preference: value }
     end
 
-    # Sets elasticsearch <tt>aggregations</tt> search request param
+    # Sets elasticsearch `aggregations` search request param
     #
+    # @example
     #  UsersIndex.filter{ name == 'Johny' }.aggregations(category_id: {terms: {field: 'category_ids'}})
     #     # => {body: {
     #            query: {...},
@@ -592,8 +608,9 @@ module Chewy
       @_fully_qualified_named_aggs[idx][type][agg_name]
     end
 
-    # Sets elasticsearch <tt>suggest</tt> search request param
+    # Sets elasticsearch `suggest` search request param
     #
+    # @example
     #  UsersIndex.suggest(name: {text: 'Joh', term: {field: 'name'}})
     #     # => {body: {
     #            query: {...},
@@ -617,6 +634,7 @@ module Chewy
     # without touching the elasticsearch server.
     # All the chained calls of methods don't affect the result
     #
+    # @example
     #   UsersIndex.none.to_a
     #     # => []
     #   UsersIndex.query(text: {name: 'Johny'}).none.to_a
@@ -630,6 +648,7 @@ module Chewy
 
     # Setups strategy for top-level filtered query
     #
+    # @example
     #    UsersIndex.filter { name == 'Johny'}.strategy(:leap_frog)
     #     # => {body: {
     #            query: { filtered: {
@@ -645,11 +664,12 @@ module Chewy
     # Adds one or more query to the search request
     # Internally queries are stored as an array
     # While the full query compilation this array compiles
-    # according to <tt>:query_mode</tt> option value
+    # according to `:query_mode` option value
     #
-    # By default it joines inside <tt>must</tt> query
-    # See <tt>#query_mode</tt> chainable method for more info.
+    # By default it joines inside `must` query
+    # See `#query_mode` chainable method for more info.
     #
+    # @example
     #   UsersIndex.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}})
     #   UsersIndex::User.query(text: {name: 'Johny'}).query(range: {age: {lte: 42}})
     #     # => {body: {
@@ -659,6 +679,7 @@ module Chewy
     # If only one query was specified, it will become a result
     # query as is, without joining.
     #
+    # @example
     #   UsersIndex.query(text: {name: 'Johny'})
     #     # => {body: {
     #            query: {text: {name: 'Johny'}}
@@ -671,14 +692,15 @@ module Chewy
     # Adds one or more filter to the search request
     # Internally filters are stored as an array
     # While the full query compilation this array compiles
-    # according to <tt>:filter_mode</tt> option value
+    # according to `:filter_mode` option value
     #
-    # By default it joins inside <tt>and</tt> filter
-    # See <tt>#filter_mode</tt> chainable method for more info.
+    # By default it joins inside `and` filter
+    # See `#filter_mode` chainable method for more info.
     #
     # Also this method supports block DSL.
-    # See <tt>Chewy::Query::Filters</tt> for more info.
+    # See `Chewy::Query::Filters` for more info.
     #
+    # @example
     #   UsersIndex.filter(term: {name: 'Johny'}).filter(range: {age: {lte: 42}})
     #   UsersIndex::User.filter(term: {name: 'Johny'}).filter(range: {age: {lte: 42}})
     #   UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }
@@ -690,6 +712,7 @@ module Chewy
     # If only one filter was specified, it will become a result
     # filter as is, without joining.
     #
+    # @example
     #   UsersIndex.filter(term: {name: 'Johny'})
     #     # => {body: {query: {filtered: {
     #            query: {...},
@@ -704,14 +727,15 @@ module Chewy
     # Adds one or more post_filter to the search request
     # Internally post_filters are stored as an array
     # While the full query compilation this array compiles
-    # according to <tt>:post_filter_mode</tt> option value
+    # according to `:post_filter_mode` option value
     #
-    # By default it joins inside <tt>and</tt> filter
-    # See <tt>#post_filter_mode</tt> chainable method for more info.
+    # By default it joins inside `and` filter
+    # See `#post_filter_mode` chainable method for more info.
     #
     # Also this method supports block DSL.
-    # See <tt>Chewy::Query::Filters</tt> for more info.
+    # See `Chewy::Query::Filters` for more info.
     #
+    # @example
     #   UsersIndex.post_filter(term: {name: 'Johny'}).post_filter(range: {age: {lte: 42}})
     #   UsersIndex::User.post_filter(term: {name: 'Johny'}).post_filter(range: {age: {lte: 42}})
     #   UsersIndex.post_filter{ name == 'Johny' }.post_filter{ age <= 42 }
@@ -722,6 +746,7 @@ module Chewy
     # If only one post_filter was specified, it will become a result
     # post_filter as is, without joining.
     #
+    # @example
     #   UsersIndex.post_filter(term: {name: 'Johny'})
     #     # => {body: {
     #            post_filter: {term: {name: 'Johny'}}
@@ -736,11 +761,10 @@ module Chewy
     # Not used if no score functions are specified
     # Possible values:
     #
-    # * <tt>:multiply</tt>
+    # * `:multiply`
     #   Default value. Query score and function result are multiplied.
     #
-    #   Ex:
-    #
+    # @example
     #     UsersIndex.boost_mode('multiply').script_score('doc['boost'].value')
     #       # => {body: {query: function_score: {
     #         query: {...},
@@ -748,23 +772,23 @@ module Chewy
     #         functions: [ ... ]
     #       }}}
     #
-    # * <tt>:replace</tt>
+    # * `:replace`
     #   Only function result is used, query score is ignored.
     #
-    # * <tt>:sum</tt>
+    # * `:sum`
     #   Query score and function score are added.
     #
-    # * <tt>:avg</tt>
+    # * `:avg`
     #   Average of query and function score.
     #
-    # * <tt>:max</tt>
+    # * `:max`
     #   Max of query and function score.
     #
-    # * <tt>:min</tt>
+    # * `:min`
     #   Min of query and function score.
     #
-    # Default value for <tt>:boost_mode</tt> might be changed
-    # with <tt>Chewy.score_mode</tt> config option.
+    # Default value for `:boost_mode` might be changed
+    # with `Chewy.score_mode` config option.
     def boost_mode(value)
       chain { criteria.update_options boost_mode: value }
     end
@@ -773,11 +797,10 @@ module Chewy
     # Not used if no score functions are specified.
     # Possible values:
     #
-    # * <tt>:multiply</tt>
+    # * `:multiply`
     #   Default value. Scores are multiplied.
     #
-    #   Ex:
-    #
+    # @example
     #     UsersIndex.score_mode('multiply').script_score('doc['boost'].value')
     #       # => {body: {query: function_score: {
     #         query: {...},
@@ -785,24 +808,25 @@ module Chewy
     #         functions: [ ... ]
     #       }}}
     #
-    # * <tt>:sum</tt>
+    # * `:sum`
     #   Scores are summed.
     #
-    # * <tt>:avg</tt>
+    # * `:avg`
     #   Scores are averaged.
     #
-    # * <tt>:first</tt>
+    # * `:first`
     #   The first function that has a matching filter is applied.
     #
-    # * <tt>:max</tt>
+    # * `:max`
     #   Maximum score is used.
     #
-    # * <tt>:min</tt>
+    # * `:min`
     #   Minimum score is used
     #
-    # Default value for <tt>:score_mode</tt> might be changed
-    # with <tt>Chewy.score_mode</tt> config option.
+    # Default value for `:score_mode` might be changed
+    # with `Chewy.score_mode` config option.
     #
+    # @example
     #   Chewy.score_mode = :first
     #
     def score_mode(value)
@@ -811,6 +835,7 @@ module Chewy
 
     # Sets search request sorting
     #
+    # @example
     #   UsersIndex.order(:first_name, :last_name).order(age: :desc).order(price: {order: :asc, mode: :avg})
     #     # => {body: {
     #            query: {...},
@@ -823,6 +848,7 @@ module Chewy
 
     # Cleans up previous search sorting and sets the new one
     #
+    # @example
     #   UsersIndex.order(:first_name, :last_name).order(age: :desc).reorder(price: {order: :asc, mode: :avg})
     #     # => {body: {
     #            query: {...},
@@ -835,6 +861,7 @@ module Chewy
 
     # Sets search request field list
     #
+    # @example
     #   UsersIndex.only(:first_name, :last_name).only(:age)
     #     # => {body: {
     #            query: {...},
@@ -847,6 +874,7 @@ module Chewy
 
     # Cleans up previous search field list and sets the new one
     #
+    # @example
     #   UsersIndex.only(:first_name, :last_name).only!(:age)
     #     # => {body: {
     #            query: {...},
@@ -858,9 +886,10 @@ module Chewy
     end
 
     # Specify types participating in the search result
-    # Works via <tt>types</tt> filter. Always merged with another filters
-    # with the <tt>and</tt> filter.
+    # Works via `types` filter. Always merged with another filters
+    # with the `and` filter.
     #
+    # @example
     #   UsersIndex.types(:admin, :manager).filters{ name == 'Johny' }.filters{ age <= 42 }
     #     # => {body: {query: {filtered: {
     #            query: {...},
@@ -893,8 +922,9 @@ module Chewy
       chain { criteria.update_types params }
     end
 
-    # Acts the same way as <tt>types</tt>, but cleans up previously set types
+    # Acts the same way as `types`, but cleans up previously set types
     #
+    # @example
     #   UsersIndex.types(:admin).types!(:manager)
     #     # => {body: {query: {filtered: {
     #            query: {...},
@@ -905,9 +935,10 @@ module Chewy
       chain { criteria.update_types params, purge: true }
     end
 
-    # Sets <tt>search_type</tt> for request.
-    # For instance, one can use <tt>search_type=count</tt> to fetch only total count of documents or to fetch only aggregations without fetching documents.
+    # Sets `search_type` for request.
+    # For instance, one can use `search_type=count` to fetch only total count of documents or to fetch only aggregations without fetching documents.
     #
+    # @example
     #   scope = UsersIndex.search_type(:count)
     #   scope.count == 0  # no documents actually fetched
     #   scope.total == 10 # but we know a total count of them
@@ -922,6 +953,7 @@ module Chewy
     # Merges two queries.
     # Merges all the values in criteria with the same rules as values added manually.
     #
+    # @example
     #   scope1 = UsersIndex.filter{ name == 'Johny' }
     #   scope2 = UsersIndex.filter{ age <= 42 }
     #   scope3 = UsersIndex.filter{ name == 'Johny' }.filter{ age <= 42 }
@@ -934,6 +966,7 @@ module Chewy
 
     # Deletes all documents matching a query.
     #
+    # @example
     #   UsersIndex.delete_all
     #   UsersIndex.filter{ age <= 42 }.delete_all
     #   UsersIndex::User.delete_all
@@ -966,6 +999,7 @@ module Chewy
 
     # Find all documents matching a query.
     #
+    # @example
     #   UsersIndex.find(42)
     #   UsersIndex.filter{ age <= 42 }.find(42)
     #   UsersIndex::User.find(42)
@@ -974,6 +1008,7 @@ module Chewy
     # In all the previous examples find will return a single object.
     # To get a collection - pass an array of ids.
     #
+    # @example
     #    UsersIndex::User.find(42, 7, 3) # array of objects with ids in [42, 7, 3]
     #    UsersIndex::User.find([8, 13])  # array of objects with ids in [8, 13]
     #    UsersIndex::User.find([42])     # array of the object with id == 42
@@ -987,6 +1022,7 @@ module Chewy
 
     # Returns true if there are at least one document that matches the query
     #
+    # @example
     #   PlacesIndex.query(...).filter(...).exists?
     #
     def exists?
@@ -995,6 +1031,7 @@ module Chewy
 
     # Sets limit to be equal to total documents count
     #
+    # @example
     #  PlacesIndex.query(...).filter(...).unlimited
     #
 
@@ -1005,6 +1042,7 @@ module Chewy
 
     # Returns request total time elapsed as reported by elasticsearch
     #
+    # @example
     #   UsersIndex.query(...).filter(...).took
     #
     def took
@@ -1019,6 +1057,7 @@ module Chewy
     # important to you than complete results, you can specify a timeout as 10 or
     # "10ms" (10 milliseconds), or "1s" (1 second). See #timeout method.
     #
+    # @example
     #   UsersIndex.query(...).filter(...).timed_out
     #
     def timed_out