Use markdown in descriptions, minor docs and code refinements

.yardopts

@@ -1,2 +1,5 @@
 --markup-provider=redcarpet
 --markup=markdown
+-
+README.md
+CHANGELOG.md

lib/chewy/search/parameters/concerns/query_storage.rb

@@ -3,12 +3,12 @@
 module Chewy
   module Search
     class Parameters
-      # This is a basic storage implementation for "query", "filter"
-      # and "post_filter" storages. It uses "bool" query as a root
-      # structure for each of them. The "bool" root is ommited on
-      # rendering if there is only a single query in the "must" or
-      # "should" array. Besides the standard parameter storage
-      # capabilities, it provides specialized methods for the "bool"
+      # This is a basic storage implementation for `query`, `filter`
+      # and `post_filter` storages. It uses `bool` query as a root
+      # structure for each of them. The `bool` root is ommited on
+      # rendering if there is only a single query in the `must` or
+      # `should` array. Besides the standard parameter storage
+      # capabilities, it provides specialized methods for the `bool`
       # query component arrays separate update.
       #
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html
@@ -18,34 +18,34 @@ class Parameters
       module QueryStorage
         DEFAULT = {must: [], should: [], must_not: []}.freeze
 
-        # Directly modifies "must" array of the root "bool" query.
+        # Directly modifies `must` array of the root `bool` query.
         # Pushes the passed query to the end of the array.
         #
         # @see Chewy::Search::QueryProxy#must
         def must(other_value)
           update!(must: other_value)
         end
 
-        # Directly modifies "should" array of the root "bool" query.
+        # Directly modifies `should` array of the root `bool` query.
         # Pushes the passed query to the end of the array.
         #
         # @see Chewy::Search::QueryProxy#should
         def should(other_value)
           update!(should: other_value)
         end
 
-        # Directly modifies "must_not" array of the root "bool" query.
+        # Directly modifies `must_not` array of the root `bool` query.
         # Pushes the passed query to the end of the array.
         #
         # @see Chewy::Search::QueryProxy#must_not
         def must_not(other_value)
           update!(must_not: other_value)
         end
 
-        # Unlike {#must} doesn't modify "must" array, but joins 2 queries
-        # into a single "must" array of the new root "bool" query.
-        # If any of the used queries is a "bool" query from the storage
-        # and contains a single query in "must" or "should" array, it will
+        # Unlike {#must} doesn't modify `must` array, but joins 2 queries
+        # into a single `must` array of the new root `bool` query.
+        # If any of the used queries is a `bool` query from the storage
+        # and contains a single query in `must` or `should` array, it will
         # be reduced to this query, so in some cases it will act exactly
         # the same way as {#must}.
         #
@@ -54,10 +54,10 @@ def and(other_value)
           replace!(must: join(other_value))
         end
 
-        # Unlike {#should} doesn't modify "should" array, but joins 2 queries
-        # into a single "should" array of the new root "bool" query.
-        # If any of the used queries is a "bool" query from the storage
-        # and contains a single query in "must" or "should" array, it will
+        # Unlike {#should} doesn't modify `should` array, but joins 2 queries
+        # into a single `should` array of the new root `bool` query.
+        # If any of the used queries is a `bool` query from the storage
+        # and contains a single query in `must` or `should` array, it will
         # be reduced to this query, so in some cases it will act exactly
         # the same way as {#should}.
         #

lib/chewy/search/parameters/filter.rb

@@ -4,14 +4,16 @@ module Chewy
   module Search
     class Parameters
       # This parameter storage doesn't have its own parameter at the
-      # ES request body. Instead, it is embedded to the root "bool"
-      # query of the "query" request parameter.
+      # ES request body. Instead, it is embedded to the root `bool`
+      # query of the `query` request parameter.
       #
       # @example
       #   scope = PlacesIndex.filter(term: {name: 'Moscow'})
       #   # => <PlacesIndex::Query {..., :body=>{:query=>{:bool=>{:filter=>{:term=>{:name=>"Moscow"}}}}}}>
       #   scope.query(match: {name: 'London'})
-      #   # => <PlacesIndex::Query {..., :body=>{:query=>{:bool=>{:must=>{:match=>{:name=>"London"}}, :filter=>{:term=>{:name=>"Moscow"}}}}}}>
+      #   # => <PlacesIndex::Query {..., :body=>{:query=>{:bool=>{
+      #   #      :must=>{:match=>{:name=>"London"}},
+      #   #      :filter=>{:term=>{:name=>"Moscow"}}}}}}>
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-filter-context.html
       # @see Chewy::Search::Parameters::QueryStorage
       class Filter < Storage

lib/chewy/search/parameters/post_filter.rb

@@ -3,7 +3,7 @@
 module Chewy
   module Search
     class Parameters
-      # A standard parameter storage, which updates "post_filter" parameter
+      # A standard parameter storage, which updates `post_filter` parameter
       # of the ES request.
       #
       # @example

lib/chewy/search/parameters/query.rb

@@ -3,7 +3,7 @@
 module Chewy
   module Search
     class Parameters
-      # A standard parameter storage, which updates "query" parameter
+      # A standard parameter storage, which updates `query` parameter
       # of the ES request.
       #
       # @example