[STORE] Added code annotations across the Persistence::Model codebase

Author: karmi

elasticsearch-persistence/lib/elasticsearch/persistence/model.rb

@@ -11,8 +11,24 @@
 module Elasticsearch
   module Persistence
 
+    # When included, extends a plain Ruby class with persistence-related features via the ActiveRecord pattern
+    #
+    # @example Include the repository in a custom class
+    #
+    #     require 'elasticsearch/persistence/model'
+    #
+    #     class MyObject
+    #       include Elasticsearch::Persistence::Repository
+    #     end
+    #
     module Model
+
+      # Utility methods for {Elasticsearch::Persistence::Model}
+      #
       module Utils
+
+        # Return Elasticsearch type based on passed Ruby class (used in the `attribute` method)
+        #
         def lookup_type(type)
           case
             when type == String
@@ -49,6 +65,9 @@ def self.included(base)
           extend  Elasticsearch::Persistence::Model::Find::ClassMethods
 
           class << self
+
+            # Re-define the Virtus' `attribute` method, to configure Elasticsearch mapping as well
+            #
             def attribute(name, type=nil, options={}, &block)
               mapping = options.delete(:mapping) || {}
               super
@@ -60,12 +79,16 @@ def attribute(name, type=nil, options={}, &block)
               gateway.mapping(&block) if block_given?
             end
 
+            # Return the {Repository::Class} instance
+            #
             def gateway(&block)
               @gateway ||= Elasticsearch::Persistence::Repository::Class.new host: self
               block.arity < 1 ? @gateway.instance_eval(&block) : block.call(@gateway) if block_given?
               @gateway
             end
 
+            # Delegate methods to repository
+            #
             delegate :settings,
                      :mappings,
                      :mapping,
@@ -79,6 +102,8 @@ def gateway(&block)
               to: :gateway
           end
 
+          # Configure the repository based on the model (set up index_name, etc)
+          #
           gateway do
             klass         base
             index_name    base.model_name.collection.gsub(/\//, '-')
@@ -96,6 +121,8 @@ def deserialize(document)
             end
           end
 
+          # Set up common attributes
+          #
           attribute :id,         String, writer: :private
           attribute :created_at, DateTime, default: lambda { |o,a| Time.now.utc }
           attribute :updated_at, DateTime, default: lambda { |o,a| Time.now.utc }

elasticsearch-persistence/lib/elasticsearch/persistence/model/rails.rb

@@ -2,15 +2,32 @@ module Elasticsearch
   module Persistence
     module Model
 
+      # Make the `Persistence::Model` models compatible with Ruby On Rails applications
+      #
       module Rails
         def self.included(base)
           base.class_eval do
+
+            # Decorates the passed in `attributes` so they extract the date & time values from Rails forms
+            #
+            # @example Correctly combine the date and time to a datetime string
+            #
+            #     params = { "published_on(1i)"=>"2014",
+            #                      "published_on(2i)"=>"1",
+            #                      "published_on(3i)"=>"1",
+            #                      "published_on(4i)"=>"12",
+            #                      "published_on(5i)"=>"00"
+            #                     }
+            #     MyRailsModel.new(params).published_on.iso8601
+            #     # => "2014-01-01T12:00:00+00:00"
+            #
             def initialize(attributes={})
               day = attributes.select { |p| p =~ /\([1-3]/ }.reduce({}) { |sum, item| (sum[item.first.gsub(/\(.+\)/, '')] ||= '' )<< item.last+'-'; sum  }
               time = attributes.select { |p| p =~ /\([4-6]/ }.reduce({}) { |sum, item| (sum[item.first.gsub(/\(.+\)/, '')] ||= '' )<< item.last+':'; sum  }
               unless day.empty? && time.empty?
                 attributes.update day.reduce({}) { |sum, item| sum[item.first] = item.last + ' ' + time[item.first]; sum }
               end
+
               super(attributes)
             end
           end

elasticsearch-persistence/lib/elasticsearch/persistence/model/store.rb

@@ -2,8 +2,20 @@ module Elasticsearch
   module Persistence
     module Model
 
+      # This module contains the storage related features of {Elasticsearch::Persistence::Model}
+      #
       module Store
-        module ClassMethods
+        module ClassMethods #:nodoc:
+
+          # Creates a class instance, saves it, if validations pass, and returns it
+          #
+          # @example Create a new person
+          #
+          #     Person.create name: 'John Smith'
+          #     # => #<Person:0x007f889e302b30 ... @id="bG7yQDAXRhCi3ZfVcx6oAA", @name="John Smith" ...>
+          #
+          # @return [Object] The model instance
+          #
           def create(attributes, options={})
             object = self.new(attributes)
             object.run_callbacks :create do
@@ -14,6 +26,23 @@ def create(attributes, options={})
         end
 
         module InstanceMethods
+
+          # Saves the model (if validations pass) and returns the response (or `false`)
+          #
+          # @example Save a valid model instance
+          #
+          #     p = Person.new(name: 'John')
+          #     p.save
+          #     => {"_index"=>"people", ... "_id"=>"RzFSXFR0R8u1CZIWNs2Gvg", "_version"=>1, "created"=>true}
+          #
+          # @example Save an invalid model instance
+          #
+          #     p = Person.new(name: nil)
+          #     p.save
+          #     # => false
+          #
+          # @return [Hash,FalseClass] The Elasticsearch response as a Hash or `false`
+          #
           def save(options={})
             return false unless valid?
             run_callbacks :save do
@@ -25,6 +54,15 @@ def save(options={})
             end
           end
 
+          # Deletes the model from Elasticsearch (if it's persisted), freezes it, and returns the response
+          #
+          # @example Delete a model instance
+          #
+          #     p.destroy
+          #     => {"_index"=>"people", ... "_id"=>"RzFSXFR0R8u1CZIWNs2Gvg", "_version"=>2 ...}
+          #
+          # @return [Hash] The Elasticsearch response as a Hash
+          #
           def destroy(options={})
             raise DocumentNotPersisted, "Object not persisted: #{self.inspect}" unless persisted?
 
@@ -37,6 +75,15 @@ def destroy(options={})
             end
           end; alias :delete :destroy
 
+          # Updates the model (via Elasticsearch's "Update" API) and returns the response
+          #
+          # @example Update a model with partial attributes
+          #
+          #     p.update name: 'UPDATED'
+          #     => {"_index"=>"people", ... "_version"=>2}
+          #
+          # @return [Hash] The Elasticsearch response as a Hash
+          #
           def update(attributes={}, options={})
             raise DocumentNotPersisted, "Object not persisted: #{self.inspect}" unless persisted?
 
@@ -48,6 +95,18 @@ def update(attributes={}, options={})
             end
           end; alias :update_attributes :update
 
+          # Increments a numeric attribute (via Elasticsearch's "Update" API) and returns the response
+          #
+          # @example Increment the `salary` attribute by 1
+          #
+          #     p.increment :salary
+          #
+          # @example Increment the `salary` attribute by 100
+          #
+          #     p.increment :salary, 100
+          #
+          # @return [Hash] The Elasticsearch response as a Hash
+          #
           def increment(attribute, value=1, options={})
             raise DocumentNotPersisted, "Object not persisted: #{self.inspect}" unless persisted?
 
@@ -56,6 +115,18 @@ def increment(attribute, value=1, options={})
             response
           end
 
+          # Decrements a numeric attribute (via Elasticsearch's "Update" API) and returns the response
+          #
+          # @example Decrement the `salary` attribute by 1
+          #
+          #     p.decrement :salary
+          #
+          # @example Decrement the `salary` attribute by 100
+          #
+          #     p.decrement :salary, 100
+          #
+          # @return [Hash] The Elasticsearch response as a Hash
+          #
           def decrement(attribute, value=1, options={})
             raise DocumentNotPersisted, "Object not persisted: #{self.inspect}" unless persisted?
 
@@ -64,6 +135,18 @@ def decrement(attribute, value=1, options={})
             response
           end
 
+          # Updates the `updated_at` attribute, saves the model and returns the response
+          #
+          # @example Update the `updated_at` attribute (default)
+          #
+          #     p.touch
+          #
+          # @example Update a custom attribute: `saved_on`
+          #
+          #     p.touch :saved_on
+          #
+          # @return [Hash] The Elasticsearch response as a Hash
+          #
           def touch(attribute=:updated_at, options={})
             raise DocumentNotPersisted, "Object not persisted: #{self.inspect}"  unless persisted?
             raise ArgumentError, "Object does not have '#{attribute}' attribute" unless respond_to?(attribute)
@@ -76,14 +159,26 @@ def touch(attribute=:updated_at, options={})
             end
           end
 
+          # Returns true when the model has been destroyed, false otherwise
+          #
+          # @return [TrueClass,FalseClass]
+          #
           def destroyed?
             !!@destroyed
           end
 
+          # Returns true when the model has been already saved to the database, false otherwise
+          #
+          # @return [TrueClass,FalseClass]
+          #
           def persisted?
             !!@persisted && !destroyed?
           end
 
+          # Returns true when the model has not been saved yet, false otherwise
+          #
+          # @return [TrueClass,FalseClass]
+          #
           def new_record?
             !persisted? && !destroyed?
           end

elasticsearch-persistence/lib/elasticsearch/persistence/repository.rb

@@ -17,10 +17,12 @@ def respond_to_missing?(method_name, *)
       end
     end
 
-    # When included, creates an instance of the {Repository::Class} class as a "gateway"
+    # When included, creates an instance of the {Repository::Class Repository} class as a "gateway"
     #
     # @example Include the repository in a custom class
     #
+    #     require 'elasticsearch/persistence'
+    #
     #     class MyRepository
     #       include Elasticsearch::Persistence::Repository
     #     end