[MODEL] Added code annotations throughout the source

Author: karmi

elasticsearch-model/lib/elasticsearch/model.rb

@@ -35,7 +35,23 @@ module Elasticsearch
   # Elasticsearch integration for Ruby models
   # =========================================
   #
-  # TODO: Description
+  # `Elasticsearch::Model` contains modules for integrating the Elasticsearch search and analytical engine
+  # with ActiveModel-based classes, or models, for the Ruby programming language.
+  #
+  # It facilitates importing your data into an index, automatically updating it when a record changes,
+  # searching the specific index, setting up the index mapping or the model JSON serialization.
+  #
+  # When the `Elasticsearch::Model` module is included in your class, it automatically extends it
+  # with the functionality; see {Elasticsearch::Model.included}. Most methods are available via
+  # the `__elasticsearch__` class and instance method proxies.
+  #
+  # It is possible to include/extend the model with the corresponding
+  # modules directly, if that is desired:
+  #
+  #     MyModel.__send__ :extend,  Elasticsearch::Model::Client::ClassMethods
+  #     MyModel.__send__ :include, Elasticsearch::Model::Client::InstanceMethods
+  #     MyModel.__send__ :extend,  Elasticsearch::Model::Searching::ClassMethods
+  #     # ...
   #
   module Model
 
@@ -45,23 +61,16 @@ module Model
     # * Includes the necessary modules in the proxy classes
     # * Sets up delegation for crucial methods such as `search`, etc.
     #
-    # @example Include the {Elasticsearch::Model} module in the `Article` model definition
+    # @example Include the module in the `Article` model definition
     #
     #     class Article < ActiveRecord::Base
     #       include Elasticsearch::Model
     #     end
     #
-    # @example Inject the {Elasticsearch::Model} module into the `Article` model
+    # @example Inject the module into the `Article` model during run time
     #
     #     Article.__send__ :include, Elasticsearch::Model
     #
-    # It is possible to include/extend the model with the corresponding
-    # modules directly, without using the proxy, if this is desired:
-    #
-    #     MyModel.__send__ :extend,  Elasticsearch::Model::Client::ClassMethods
-    #     MyModel.__send__ :include, Elasticsearch::Model::Client::InstanceMethods
-    #     MyModel.__send__ :extend,  Elasticsearch::Model::Searching::ClassMethods
-    #     # ...
     #
     def self.included(base)
       base.class_eval do
@@ -100,6 +109,19 @@ module ClassMethods
 
       # Get or set the client for all models
       #
+      # @example Get the client
+      #
+      #     Elasticsearch::Model.client
+      #     => #<Elasticsearch::Transport::Client:0x007f96a7d0d000 @transport=... >
+      #
+      # @example Configure (set) the client for all the models
+      #
+      #     Elasticsearch::Model.client Elasticsearch::Client.new host: 'http://localhost:9200', tracer: true
+      #     => #<Elasticsearch::Transport::Client:0x007f96a6dd0d80 @transport=... >
+      #
+      # @note You have to set the client before you call Elasticsearch methods on the model,
+      #       or set it directly on the model; see {Elasticsearch::Model::Client::ClassMethods#client}
+      #
       def client client=nil
         @client = client || @client || Elasticsearch::Client.new
       end

elasticsearch-model/lib/elasticsearch/model/adapter.rb

@@ -1,45 +1,137 @@
 module Elasticsearch
   module Model
+
+    # Contains an adapter which provides OxM-specific implementations for common behaviour:
+    #
+    # * {Adapter::Adapter#records_mixin   Fetching records from the database}
+    # * {Adapter::Adapter#callbacks_mixin Model callbacks for automatic index updates}
+    # * {Adapter::Adapter#importing_mixin Efficient bulk loading from the database}
+    #
+    # @see Elasticsearch::Model::Adapter::Default
+    # @see Elasticsearch::Model::Adapter::ActiveRecord
+    # @see Elasticsearch::Model::Adapter::Mongoid
+    #
     module Adapter
+
+      # Returns an adapter based on the Ruby class passed
+      #
+      # @example Create an adapter for an ActiveRecord-based model
+      #
+      #     class Article < ActiveRecord::Base; end
+      #
+      #     myadapter = Elasticsearch::Model::Adapter.from_class(Article)
+      #     myadapter.adapter
+      #     # => Elasticsearch::Model::Adapter::ActiveRecord
+      #
+      # @see Adapter.adapters The list of included adapters
+      # @see Adapter.register Register a custom adapter
+      #
       def from_class(klass)
         Adapter.new(klass)
       end; module_function :from_class
 
+      # Returns registered adapters
+      #
+      # @see ::Elasticsearch::Model::Adapter::Adapter.adapters
+      #
       def adapters
         Adapter.adapters
       end; module_function :adapters
 
+      # Registers an adapter
+      #
+      # @see ::Elasticsearch::Model::Adapter::Adapter.register
+      #
       def register(name, condition)
         Adapter.register(name, condition)
       end; module_function :register
 
+      # Contains an adapter for specific OxM or architecture.
+      #
       class Adapter
         attr_reader :klass
 
         def initialize(klass)
           @klass = klass
         end
 
+        # Registers an adapter for specific condition
+        #
+        # @param name      [Module] The module containing the implemented interface
+        # @param condition [Proc]   An object with a `call` method which is evaluated in {.adapter}
+        #
+        # @example Register an adapter for DataMapper
+        #
+        #     module DataMapperAdapter
+        #
+        #       # Implement the interface for fetching records
+        #       #
+        #       module Records
+        #         def records
+        #           klass.all(id: @ids)
+        #         end
+        #
+        #         # ...
+        #       end
+        #     end
+        #
+        #     # Register the adapter
+        #     #
+        #     Elasticsearch::Model::Adapter.register(
+        #       DataMapperAdapter,
+        #       lambda { |klass|
+        #         defined?(::DataMapper::Resource) and klass.ancestors.include?(::DataMapper::Resource)
+        #       }
+        #     )
+        #
         def self.register(name, condition)
           self.adapters[name] = condition
         end
 
+        # Return the collection of registered adapters
+        #
+        # @example Return the currently registered adapters
+        #
+        #     Elasticsearch::Model::Adapter.adapters
+        #     # => {
+        #     #  Elasticsearch::Model::Adapter::ActiveRecord => #<Proc:0x007...(lambda)>,
+        #     #  Elasticsearch::Model::Adapter::Mongoid => #<Proc:0x007... (lambda)>,
+        #     # }
+        #
+        # @return [Hash] The collection of adapters
+        #
         def self.adapters
           @adapters ||= {}
         end
 
+        # Return the module with {Default::Records} interface implementation
+        #
+        # @api private
+        #
         def records_mixin
           adapter.const_get(:Records)
         end
 
+        # Return the module with {Default::Callbacks} interface implementation
+        #
+        # @api private
+        #
         def callbacks_mixin
           adapter.const_get(:Callbacks)
         end
 
+        # Return the module with {Default::Importing} interface implementation
+        #
+        # @api private
+        #
         def importing_mixin
           adapter.const_get(:Importing)
         end
 
+        # Returns the adapter module
+        #
+        # @api private
+        #
         def adapter
           @adapter ||= begin
             self.class.adapters.find( lambda {[]} ) { |name, condition| condition.call(klass) }.first \

elasticsearch-model/lib/elasticsearch/model/adapters/active_record.rb

@@ -1,14 +1,17 @@
 module Elasticsearch
   module Model
     module Adapter
+
+      # An adapter for ActiveRecord-based models
+      #
       module ActiveRecord
 
         Adapter.register self,
                          lambda { |klass| defined?(::ActiveRecord::Base) && klass.ancestors.include?(::ActiveRecord::Base) }
 
         module Records
 
-          # Return the `ActiveRecord::Relation` instance
+          # Returns an `ActiveRecord::Relation` instance
           #
           def records
             sql_records = klass.where(id: @ids)
@@ -32,7 +35,7 @@ def load
             records.load
           end
 
-          # Intercept call to order, so we can ignore the order from Elasticsearch
+          # Intercept call to the `order` method, so we can ignore the order from Elasticsearch
           #
           def order(*args)
             sql_records = records.__send__ :order, *args
@@ -48,6 +51,12 @@ def order(*args)
         end
 
         module Callbacks
+
+          # Handle index updates (creating, updating or deleting documents)
+          # when the model changes, by hooking into the lifecycle
+          #
+          # @see http://guides.rubyonrails.org/active_record_callbacks.html
+          #
           def self.included(base)
             base.class_eval do
               after_commit lambda { __elasticsearch__.index_document  },  on: [:create]
@@ -58,9 +67,10 @@ def self.included(base)
         end
 
         module Importing
+
           # Fetch batches of records from the database
           #
-          # Use the [`find_in_batches`](http://api.rubyonrails.org/classes/ActiveRecord/Batches.html) method
+          # @see http://api.rubyonrails.org/classes/ActiveRecord/Batches.html ActiveRecord::Batches.find_in_batches
           #
           def __find_in_batches(options={}, &block)
             find_in_batches(options) do |batch|

elasticsearch-model/lib/elasticsearch/model/adapters/default.rb

@@ -1,21 +1,38 @@
 module Elasticsearch
   module Model
     module Adapter
+
+      # The default adapter for models which haven't one registered
+      #
       module Default
 
+        # Module for implementing methods and logic related to fetching records from the database
+        #
         module Records
-          # Use `ActiveModel#find`
+
+          # Return the collection of records fetched from the database
+          #
+          # By default uses `MyModel#find[1, 2, 3]`
           #
           def records
             klass.find(@ids)
           end
         end
 
+        # Module for implementing methods and logic related to hooking into model lifecycle
+        # (e.g. to perform automatic index updates)
+        #
+        # @see http://api.rubyonrails.org/classes/ActiveModel/Callbacks.html
         module Callbacks
           # noop
         end
 
+        # Module for efficiently fetching records from the database to import them into the index
+        #
         module Importing
+
+          # @abstract Implement this method in your adapter
+          #
           def __find_in_batches(options={}, &block)
             raise NoMethodError, "Method not implemented for default adapter"
           end
@@ -24,4 +41,4 @@ def __find_in_batches(options={}, &block)
       end
     end
   end
-end
+end

elasticsearch-model/lib/elasticsearch/model/adapters/mongoid.rb

@@ -1,13 +1,19 @@
 module Elasticsearch
   module Model
     module Adapter
+
+      # An adapter for Mongoid-based models
+      #
+      # @see http://mongoid.org
+      #
       module Mongoid
 
         Adapter.register self,
                          lambda { |klass| defined?(::Mongoid::Document) && klass.ancestors.include?(::Mongoid::Document) }
 
         module Records
-          # Return the `ActiveRecord::Relation` instance
+
+          # Return a `Mongoid::Criteria` instance
           #
           def records
             criteria = klass.where(:id.in => @ids)
@@ -36,6 +42,12 @@ def records
         end
 
         module Callbacks
+
+          # Handle index updates (creating, updating or deleting documents)
+          # when the model changes, by hooking into the lifecycle
+          #
+          # @see http://mongoid.org/en/mongoid/docs/callbacks.html
+          #
           def self.included(base)
             base.after_create  { |document| document.__elasticsearch__.index_document  }
             base.after_update  { |document| document.__elasticsearch__.update_document }
@@ -44,6 +56,7 @@ def self.included(base)
         end
 
         module Importing
+
           # Fetch batches of records from the database
           #
           # @see https://github.com/mongoid/mongoid/issues/1334

elasticsearch-model/lib/elasticsearch/model/callbacks.rb

@@ -1,7 +1,30 @@
 module Elasticsearch
   module Model
+
+    # Allows to automatically update index based on model changes,
+    # by hooking into the model lifecycle.
+    #
+    # @note A blocking HTTP request is done during the update process.
+    #       If you need a more performant/resilient way of updating the index,
+    #       consider adapting the callbacks behaviour, and use a background
+    #       processing solution such as [Sidekiq](http://sidekiq.org)
+    #       or [Resque](https://github.com/resque/resque).
+    #
     module Callbacks
 
+      # When included in a model, automatically injects the callback subscribers (`after_save`, etc)
+      #
+      # @example Automatically update Elasticsearch index when the model changes
+      #
+      #     class Article
+      #       include Elasticsearch::Model
+      #       include Elasticsearch::Model::Callbacks
+      #     end
+      #
+      #     Article.first.update_attribute :title, 'Updated'
+      #     #  SQL (0.3ms)  UPDATE "articles" SET "title" = ...
+      #     #  2013-11-20 15:08:52 +0100: POST http://localhost:9200/articles/article/1/_update ...
+      #
       def self.included(base)
         adapter = Adapter.from_class(base)
         base.__send__ :include, adapter.callbacks_mixin