Merge pull request #496 from raspygold/readme-updates

Readme updates for delete_by and update_if option

README.md

@@ -48,7 +48,7 @@ To add PgSearch to an Active Record model, simply include the PgSearch module.
 class Shape < ActiveRecord::Base
   include PgSearch::Model
 end
-```    
+```
 
 ### Contents
 * [Multi-search vs. search scopes](#multi-search-vs-search-scopes)
@@ -198,17 +198,22 @@ problematic_record.published?     # => true
 PgSearch.multisearch("timestamp") # => Includes problematic_record
 ```
 
-#### More Options 
+#### More Options
 
 **Conditionally update pg_search_documents**
 
-You can specify an `:update_if` parameter to conditionally update pg_search documents. For example:
+You can also use the `:update_if` option to pass a Proc or method name to call
+to determine whether or not a particular record should be updated.
+
+Note that the Proc or method name is called in an `after_save` hook, so if you
+are relying on ActiveRecord dirty flags use `*_previously_changed?`.
 
 ```ruby
-multisearchable(
-    against: [:body],
-    update_if: :body_changed?
-  )
+class Message < ActiveRecord::Base
+  include PgSearch::Model
+  multisearchable against: [:body],
+                  update_if: :body_previously_changed?
+end
 ```
 
 **Specify additional attributes to be saved on the pg_search_documents table**
@@ -241,7 +246,8 @@ This allows much faster searches without joins later on by doing something like:
 PgSearch.multisearch(params['search']).where(author_id: 2)
 ```
 
-*NOTE: You must currently manually call `record.update_pg_search_document` for the additional attribute to be included in the pg_search_documents table*
+*NOTE: You must currently manually call `record.update_pg_search_document` for
+the additional attribute to be included in the pg_search_documents table*
 
 #### Multi-search associations
 
@@ -353,15 +359,11 @@ pg_search_documents tables. The following will set the schema search path to
 
     $ rake pg_search:multisearch:rebuild[BlogPost,my_schema]
 
-For models that are multisearchable :against methods that directly map to
+For models that are multisearchable `:against` methods that directly map to
 Active Record attributes, an efficient single SQL statement is run to update
-the pg_search_documents table all at once. However, if you call any dynamic
-methods in :against, the following strategy will be used:
-
-```ruby
-PgSearch::Document.delete_all(searchable_type: "Ingredient")
-Ingredient.find_each { |record| record.update_pg_search_document }
-```
+the `pg_search_documents` table all at once. However, if you call any dynamic
+methods in `:against` then `update_pg_search_document` will be called on the
+individual records being indexed in batches.
 
 You can also provide a custom implementation for rebuilding the documents by
 adding a class method called `rebuild_pg_search_documents` to your model.
@@ -555,8 +557,8 @@ Here's an example if you pass multiple :using options with additional configurat
 ```ruby
 class Beer < ActiveRecord::Base
   include PgSearch::Model
-  pg_search_scope :search_name, 
-  against: :name, 
+  pg_search_scope :search_name,
+  against: :name,
   using: {
       :trigram => {},
       :dmetaphone => {},
@@ -677,7 +679,7 @@ Animal.with_name_matching("fish !red !blue") # => [one_fish, two_fish]
 
 PostgreSQL full text search also support multiple dictionaries for stemming.
 You can learn more about how dictionaries work by reading the [PostgreSQL
-documention](http://www.postgresql.org/docs/current/static/textsearch-dictionaries.html). 
+documention](http://www.postgresql.org/docs/current/static/textsearch-dictionaries.html).
 If you use one of the language dictionaries, such as "english",
 then variants of words (e.g. "jumping" and "jumped") will match each other. If
 you don't want stemming, you should pick the "simple" dictionary which does
@@ -849,7 +851,7 @@ used for searching.
 Double Metaphone support is currently available as part of the [fuzzystrmatch
 extension](http://www.postgresql.org/docs/current/static/fuzzystrmatch.html)
 that must be installed before this feature can be used. In addition to the
-extension, you must install a utility function into your database. To generate 
+extension, you must install a utility function into your database. To generate
 and run a migration for this, run:
 
     $ rails g pg_search:migration:dmetaphone
@@ -884,7 +886,7 @@ Trigram search works by counting how many three-letter substrings (or
 Trigram search has some ability to work even with typos and misspellings in
 the query or text.
 
-Trigram support is currently available as part of the 
+Trigram support is currently available as part of the
 [pg_trgm extension](http://www.postgresql.org/docs/current/static/pgtrgm.html) that must be installed before this
 feature can be used.
 
@@ -948,7 +950,7 @@ Vegetable.strictly_spelled_like("collyflower") # => []
 Allows you to match words in longer strings.
 By default, trigram searches use `%` or `similarity()` as a similarity value.
 Set `word_similarity` to `true` to opt for `<%` and `word_similarity` instead.
-This causes the trigram search to use the similarity of the query term 
+This causes the trigram search to use the similarity of the query term
 and the word with greatest similarity.
 
 ```ruby
@@ -974,12 +976,12 @@ Sentence.similarity_like("word") # => []
 Sentence.word_similarity_like("word") # => [sentence]
 ```
 
-### Limiting Fields When Combining Features 
+### Limiting Fields When Combining Features
 
-Sometimes when doing queries combining different features you 
+Sometimes when doing queries combining different features you
 might want to searching against only some of the fields with certain features.
 For example perhaps you want to only do a trigram search against the shorter fields
-so that you don't need to reduce the threshold excessively. You can specify 
+so that you don't need to reduce the threshold excessively. You can specify
 which fields using the 'only' option:
 
 ```ruby
@@ -998,7 +1000,7 @@ class Image < ActiveRecord::Base
 end
 ```
 
-Now you can succesfully retrieve an Image with a file_name: 'image_foo.jpg' 
+Now you can succesfully retrieve an Image with a file_name: 'image_foo.jpg'
 and long_description: 'This description is so long that it would make a trigram search
 fail any reasonable threshold limit' with: