hydra_attribute 0.4.0.rc1 → 0.4.0.rc2

data/lib/hydra_attribute/hydra_methods.rb

@@ -1,7 +1,9 @@
 module HydraAttribute
+
+  # @see HydraAttribute::HydraMethods::ClassMethods ClassMethods for additional documentation
   module HydraMethods
     extend ActiveSupport::Concern
-    extend Memoize
+    extend Memoizable
 
     include HydraSetMethods
     include HydraAttributeMethods
@@ -12,31 +14,234 @@ module HydraAttribute
     end
 
     module ClassMethods
-      extend Memoize
+      extend Memoizable
 
-      def hydra_set_attributes(hydra_set_id)
-        hydra_set = hydra_set(hydra_set_id)
+      # Finds attribute for attribute sets. Returns all attributes if attribute set is undefined.
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_set.hydra_attributes.create(name: 'color', backend_type: 'string')
+      #
+      #   Product.hydra_set_attributes('Default')
+      #   # [<HydraAttribute::HydraAttribute name: "title">, <HydraAttribute::HydraAttribute name: "color">]
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #
+      #   Product.hydra_set_attributes('FAKE')
+      #   # [<HydraAttribute::HydraAttribute name: "name">, <HydraAttribute::HydraAttribute name: "title">]
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [ActiveRecord::Relation] contains preloaded attribute models
+      def hydra_set_attributes(hydra_set_identifier)
+        hydra_set = hydra_set(hydra_set_identifier)
         hydra_set.nil? ? hydra_attributes : hydra_set.hydra_attributes
       end
 
-      %w(id name backend_type).each do |prefix|
+      # Returns backend types for attributes which are assigned to passed attribute set.
+      # If attribute set doesn't exist, return all attribute backend types.
+      #
+      # @note This method is cacheable
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attribute_backend_types('Default')
+      #   # ["float", "boolean"]
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attribute_backend_types('FAKE')
+      #   # ["string", float", "boolean"]
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [Array<String>] contains unique list of attribute backend types
+      def hydra_set_attribute_backend_types(hydra_set_identifier)
+        hydra_set_attributes(hydra_set_identifier).map(&:backend_type).uniq
+      end
+      hydra_memoize :hydra_set_attribute_backend_types
+
+      # @!method hydra_set_attribute_ids(hydra_set_identifier)
+      # Returns ids for attributes which are assigned to passed attribute set.
+      # If attribute set doesn't exist, return all attribute ids.
+      #
+      # @note This method is cacheable
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')      # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')    # 2
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean') # 3
+      #
+      #   Product.hydra_set_attribute_ids('Default')
+      #   # [2, 3]
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')      # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')    # 2
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean') # 3
+      #
+      #   Product.hydra_set_attribute_ids('FAKE')
+      #   # [1, 2, 3]
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [Array<Fixnum>] contains unique list of attribute ids
+
+      # @!method hydra_set_attribute_names(hydra_set_identifier)
+      # Returns names for attributes which are assigned to passed attribute set.
+      # If attribute set doesn't exist, return all attribute names.
+      #
+      # @note This method is cacheable
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attribute_names('Default')
+      #   # ["price", "active"]
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attribute_names('FAKE')
+      #   # ["name", "price", "active"]
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [Array<String>] contains unique list of attribute names
+      %w(id name).each do |prefix|
         module_eval <<-EOS, __FILE__, __LINE__ + 1
-          def hydra_set_attribute_#{prefix}s(hydra_set_id)
-            hydra_set_attributes(hydra_set_id).map(&:#{prefix})
+          def hydra_set_attribute_#{prefix}s(hydra_set_identifier)
+            hydra_set_attributes(hydra_set_identifier).map(&:#{prefix})
           end
           hydra_memoize :hydra_set_attribute_#{prefix}s
         EOS
       end
 
-      def hydra_set_attributes_by_backend_type(hydra_set_id)
-        hydra_set_attributes(hydra_set_id).group_by(&:backend_type)
+      # Groups attributes for attribute set by backend type.
+      # If attribute set doesn't exist, group all attributes.
+      #
+      # @note This method is cacheable
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attributes_by_backend_type('Default')
+      #   # {
+      #   #    "float"=>[<HydraAttribute::HydraAttribute name: 'price'>],
+      #   #    "boolean"=>[<HydraAttribute::HydraAttribute name: 'active'>]
+      #   # }
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attributes_by_backend_type('FAKE')
+      #   # {
+      #   #    "string"=>[<HydraAttribute::HydraAttribute name: 'name'>],
+      #   #    "float"=>[<HydraAttribute::HydraAttribute name: 'price'>],
+      #   #    "boolean"=>[<HydraAttribute::HydraAttribute name: 'active'>]
+      #   # }
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [Hash{String => Array<HydraAttribute::HydraAttribute>}] contains grouped attributes by their backend types
+      def hydra_set_attributes_by_backend_type(hydra_set_identifier)
+        hydra_set_attributes(hydra_set_identifier).group_by(&:backend_type)
       end
       hydra_memoize :hydra_set_attributes_by_backend_type
 
+      # @!method hydra_set_attribute_ids_by_backend_type(hydra_set_identifier)
+      # Groups attribute ids for attribute set by backend type.
+      # If attribute set doesn't exist, group all attribute ids.
+      #
+      # @note This method is cacheable
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')      # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')    # 2
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean') # 3
+      #
+      #   Product.hydra_set_attribute_ids_by_backend_type('Default')
+      #   # {"float"=>[2], "boolean"=>[3]}
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')      # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')    # 2
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean') # 3
+      #
+      #   Product.hydra_set_attribute_ids_by_backend_type('FAKE')
+      #   # {"string"=>[1], "float"=>[2], "boolean"=>[3]}
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [Hash{String => Array<Fixnum>}] contains grouped attribute ids by their backend types
+
+      # @!method hydra_set_attribute_names_by_backend_type(hydra_set_identifier)
+      # Groups attribute names for attribute set by backend type.
+      # If attribute set doesn't exist, group all attribute names.
+      #
+      # @note This method is cacheable
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attribute_names_by_backend_type('Default')
+      #   # {"float"=>["price"], "boolean"=>["active"]}
+      #
+      # @example attribute set doesn't exist
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #   hydra_set.hydra_attributes.create(name: 'active', backend_type: 'boolean')
+      #
+      #   Product.hydra_set_attribute_names_by_backend_type('FAKE')
+      #   # {"string"=>["name"], "float"=>["price"], "boolean"=>["active"]}
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @return [Hash{String => Array<String>}] contains grouped attribute names by their backend types
       %w(id name).each do |prefix|
         module_eval <<-EOS, __FILE__, __LINE__ + 1
-          def hydra_set_attribute_#{prefix}s_by_backend_type(hydra_set_id)
-            hydra_set_attributes(hydra_set_id).each_with_object({}) do |hydra_attribute, object|
+          def hydra_set_attribute_#{prefix}s_by_backend_type(hydra_set_identifier)
+            hydra_set_attributes(hydra_set_identifier).each_with_object({}) do |hydra_attribute, object|
               object[hydra_attribute.backend_type] ||= []
               object[hydra_attribute.backend_type] << hydra_attribute.#{prefix}
             end
@@ -45,20 +250,141 @@ module HydraAttribute
         EOS
       end
 
-      def hydra_set_attributes_for_backend_type(hydra_set_id, backend_type)
-        hydra_attributes = hydra_set_attributes_by_backend_type(hydra_set_id)[backend_type]
+      # Returns attributes for attribute set and backend type.
+      # If attribute set doesn't exist, returns all attributes for backend type.
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #
+      #   Product.hydra_set_attributes_for_backend_type('Default', 'float')
+      #   # [<HydraAttribute::HydraAttribute name: "price">]
+      #
+      # @example attribute set doesn't exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #
+      #   Product.hydra_set_attributes_for_backend_type('FAKE', 'string')
+      #   # [<HydraAttribute::HydraAttribute name: "name">, <HydraAttribute::HydraAttribute name: "title">]
+      #
+      # @example attributes doesn't exist for backend type
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #
+      #   Product.hydra_set_attributes_for_backend_type('Default', 'boolean')
+      #   # []
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @param backend_type [String] see HydraAttribute::SUPPORTED_BACKEND_TYPES
+      # @return [Array] contains attribute models
+      def hydra_set_attributes_for_backend_type(hydra_set_identifier, backend_type)
+        hydra_attributes = hydra_set_attributes_by_backend_type(hydra_set_identifier)[backend_type]
         hydra_attributes.nil? ? [] : hydra_attributes
       end
 
+      # @!method hydra_set_attribute_ids_for_backend_type(hydra_set_identifier, backend_type)
+      # Returns attribute ids for attribute set and backend type.
+      # If attribute set doesn't exist, returns all attribute ids for backend type.
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')     # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string') # 2
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')  # 3
+      #
+      #   Product.hydra_set_attribute_ids_for_backend_type('Default', 'float')      # [2]
+      #
+      # @example attribute set doesn't exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')     # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string') # 2
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')  # 3
+      #
+      #   Product.hydra_set_attribute_ids_for_backend_type('FAKE', 'string')        # [1, 2]
+      #
+      # @example attributes doesn't exist for backend type
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')     # 1
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string') # 2
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')  # 3
+      #
+      #   Product.hydra_set_attribute_ids_for_backend_type('Default', 'boolean')    # []
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @param backend_type [String] see HydraAttribute::SUPPORTED_BACKEND_TYPES
+      # @return [Array<Fixnum>] contains attribute ids
+
+      # @!method hydra_set_attribute_names_for_backend_type(hydra_set_identifier, backend_type)
+      # Returns attribute names for attribute set and backend type.
+      # If attribute set doesn't exist, returns all attribute names for backend type.
+      #
+      # @example attribute set exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #
+      #   Product.hydra_set_attribute_names_for_backend_type('Default', 'float') # ["price"]
+      #
+      # @example attribute set doesn't exists
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #
+      #   Product.hydra_set_attribute_names_for_backend_type('FAKE', 'string') # ["name", "title"]
+      #
+      # @example attributes doesn't exist for backend type
+      #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+      #
+      #   hydra_set = Product.hydra_sets.create(name: 'Default')
+      #   hydra_sets.hydra_attributes.create(name: 'title', backend_type: 'string')
+      #   hydra_sets.hydra_attributes.create(name: 'price', backend_type: 'float')
+      #
+      #   Product.hydra_set_attribute_names_for_backend_type('Default', 'boolean') # []
+      #
+      # @param hydra_set_identifier [Fixnum, String] id or name of attribute set
+      # @param backend_type [String] see HydraAttribute::SUPPORTED_BACKEND_TYPES
+      # @return [Array<String>] contains attribute names
       %w(id name).each do |prefix|
         module_eval <<-EOS, __FILE__, __LINE__ + 1
-          def hydra_set_attribute_#{prefix}s_for_backend_type(hydra_set_id, backend_type)
-            values = hydra_set_attribute_#{prefix}s_by_backend_type(hydra_set_id)[backend_type]
+          def hydra_set_attribute_#{prefix}s_for_backend_type(hydra_set_identifier, backend_type)
+            values = hydra_set_attribute_#{prefix}s_by_backend_type(hydra_set_identifier)[backend_type]
             values.nil? ? [] : values
           end
         EOS
       end
 
+      # Clear cache for the following methods:
+      # * hydra_set_attributes(hydra_set_identifier)
+      # * hydra_set_attribute_ids(hydra_set_identifier)
+      # * hydra_set_attribute_names(hydra_set_identifier)
+      # * hydra_set_attribute_backend_types(hydra_set_identifier)
+      # * hydra_set_attributes_by_backend_type(hydra_set_identifier)
+      # * hydra_set_attribute_ids_by_backend_type(hydra_set_identifier)
+      # * hydra_set_attribute_names_by_backend_type(hydra_set_identifier)
+      #
+      # Also calls the following methods:
+      # * clear_hydra_set_cache!
+      # * clear_hydra_attribute_cache!
+      # * clear_hydra_value_cache!
+      #
+      # @note This method should not be called manually. It used for hydra_attribute gem engine.
+      # @return [NilClass]
       def clear_hydra_method_cache!
         clear_hydra_set_cache!
         clear_hydra_attribute_cache!
@@ -78,6 +404,22 @@ module HydraAttribute
       end
     end
 
+    # Returns hash with attribute names and values based on attribute set.
+    #
+    # @example
+    #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+    #
+    #   hydra_set = Product.hydra_sets.create(name: 'Default')
+    #   hydra_set.hydra_attributes.create(name: 'title', backend_type: 'string')
+    #   hydra_set.hydra_attributes.create(name: 'color', backend_type: 'string')
+    #
+    #   product = Product.new
+    #   product.hydra_attributes # {"name"=>nil, "title"=>nil, "color"=>nil}
+    #
+    #   product.hydra_set_id = hydra_set.id
+    #   product.hydra_attributes # {"title"=>nil, "color"=>nil}
+    #
+    # @return [Hash] contains attribute names and values
     def hydra_attributes
       hydra_value_models.inject({}) do |hydra_attributes, model|
         hydra_attributes[model.hydra_attribute_name] = model.value
@@ -85,6 +427,59 @@ module HydraAttribute
       end
     end
 
+    # @!method hydra_attribute_ids
+    # Returns attribute ids
+    #
+    # @example
+    #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')    # 1
+    #
+    #   hydra_set = Product.hydra_sets.create(name: 'Default')
+    #   hydra_set.hydra_attributes.create(name: 'title', backend_type: 'string') # 2
+    #   hydra_set.hydra_attributes.create(name: 'color', backend_type: 'string') # 3
+    #
+    #   product = Product.new
+    #   product.hydra_attribute_ids # [1, 2, 3]
+    #
+    #   product.hydra_set_id = hydra_set.id
+    #   product.hydra_attribute_ids # [2, 3]
+    #
+    # @return [Array] contains attribute ids
+
+    # @!method hydra_attribute_names
+    # Returns attribute names
+    #
+    # @example
+    #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+    #
+    #   hydra_set = Product.hydra_sets.create(name: 'Default')
+    #   hydra_set.hydra_attributes.create(name: 'title', backend_type: 'string')
+    #   hydra_set.hydra_attributes.create(name: 'color', backend_type: 'string')
+    #
+    #   product = Product.new
+    #   product.hydra_attribute_names # ["name", "title", "color"]
+    #
+    #   product.hydra_set_id = hydra_set.id
+    #   product.hydra_attribute_names # ["title", "color"]
+    #
+    # @return [Array] contains attribute names
+
+    # @!method hydra_attribute_backend_types
+    # Returns attribute backend types
+    #
+    # @example
+    #   Product.hydra_attributes.create(name: 'name', backend_type: 'string')
+    #
+    #   hydra_set = Product.hydra_sets.create(name: 'Default')
+    #   hydra_set.hydra_attributes.create(name: 'price', backend_type: 'float')
+    #   hydra_set.hydra_attributes.create(name: 'total', backend_type: 'integer')
+    #
+    #   product = Product.new
+    #   product.hydra_attribute_backend_types # ["string", "float", "integer"]
+    #
+    #   product.hydra_set_id = hydra_set.id
+    #   product.hydra_attribute_backend_types # ["float", "integer"]
+    #
+    # @return [Array] contains attribute backend types
     %w(ids names backend_types).each do |prefix|
       module_eval <<-EOS, __FILE__, __LINE__ + 1
         def hydra_attribute_#{prefix}
@@ -93,6 +488,11 @@ module HydraAttribute
       EOS
     end
 
+    # Finds attribute representation as a model by identifier
+    #
+    # @note This method is cacheable
+    # @param identifier [Fixnum, String] id or name of attribute
+    # @return [ActiveRecord::Base]
     def hydra_value_model(identifier)
       hydra_attribute = self.class.hydra_attribute(identifier)
       if hydra_attribute
@@ -102,6 +502,10 @@ module HydraAttribute
     end
     hydra_memoize :hydra_value_model
 
+    # Returns all attributes as models
+    #
+    # @note This method is cacheable
+    # @return [Array] contains values models
     def hydra_value_models
       self.class.hydra_set_attribute_backend_types(hydra_set_id).inject([]) do |models, backend_type|
         models + hydra_value_association(backend_type).all_models
@@ -110,6 +514,7 @@ module HydraAttribute
     hydra_memoize :hydra_value_models
 
     private
+      # Resets locked attributes after setting new hydra_set_id
       def write_attribute_with_hydra_set_id(attr_name, value)
         if attr_name.to_s == 'hydra_set_id'
           self.class.hydra_attribute_backend_types.each do |backend_type|

data/lib/hydra_attribute/hydra_set_methods.rb

@@ -1,18 +1,47 @@
 module HydraAttribute
+  # This error is raised when called method for attribute which doesn't exist in current hydra set
+  #
+  # @example
+  #   Product.hydra_attributes.create(name: 'price', backend_type: 'float')
+  #   Product.hydra_attributes.create(name: 'title', backend_type: 'string')
+  #
+  #   hydra_set = Product.hydra_sets.create(name: 'Default')
+  #   hydra_set.hydra_attributes = [Product.hydra_attribute('title')]
+  #
+  #   product = Product.new(hydra_set_id: hydra_set.id)
+  #   product.title = 'Toy' # ok
+  #   product.price = 2.50  # raise HydraAttribute::MissingAttributeInHydraSetError
   class MissingAttributeInHydraSetError < NoMethodError
   end
 
+  # @see HydraAttribute::HydraSetMethods::ClassMethods ClassMethods for documentation
   module HydraSetMethods
     extend ActiveSupport::Concern
 
     module ClassMethods
-      extend Memoize
+      extend Memoizable
 
+      # Returns attribute sets for current entity.
+      #
+      # @note This method is cacheable, therefore just one request to database is used
+      # @example
+      #   Product.hydra_sets                         # [<HydraAttribute::HydraSet>, ...]
+      #   Product.hydra_sets.create(name: 'Default') # create attribute set
+      #   Product.hydra_sets.each(&:destroy)         # remove all attribute sets
+      # @return [ActiveRecord::Relation] contains preloaded attribute sets
       def hydra_sets
         HydraSet.where(entity_type: base_class.model_name)
       end
       hydra_memoize :hydra_sets
 
+      # Finds attribute set by name or id
+      #
+      # @note This method is cacheable, therefore it's better to use it instead of manually searching.
+      # @example
+      #   Product.hydra_set(10)        # or
+      #   Product.hydra_set('Default')
+      # @param identifier [Fixnum, String] id or name of attribute set
+      # @return [HydraAttribute::HydraSet, NilClass] attribute set model or +nil+
       def hydra_set(identifier)
         hydra_sets.find do |hydra_set|
           hydra_set.id == identifier || hydra_set.name == identifier
@@ -20,6 +49,25 @@ module HydraAttribute
       end
       hydra_memoize :hydra_set
 
+      # @!method hydra_set_ids
+      # Returns all attribute set ids
+      #
+      # @note This method is cacheable.
+      # @example
+      #   Product.hydra_sets.create(name: 'First')  # 1
+      #   Product.hydra_sets.create(name: 'Second') # 2
+      #   Product.hydra_set_ids                     # [1, 2]
+      # @return [Array<Fixnum>] contains attribute set ids
+
+      # @!method hydra_set_names
+      # Returns all attribute set names
+      #
+      # @note This method is cacheable.
+      # @example
+      #   Product.hydra_sets.create(name: 'First')  # 1
+      #   Product.hydra_sets.create(name: 'Second') # 2
+      #   Product.hydra_set_names                   # ["First", "Second"]
+      # @return [Array<Fixnum>] contains attribute set names
       %w(id name).each do |prefix|
         module_eval <<-EOS, __FILE__, __LINE__ + 1
           def hydra_set_#{prefix}s
@@ -29,6 +77,14 @@ module HydraAttribute
         EOS
       end
 
+      # Clear cache for the following methods:
+      # * hydra_sets
+      # * hydra_set(identifier)
+      # * hydra_set_ids
+      # * hydra_set_names
+      #
+      # @note This method should not be called manually. It used for hydra_attribute gem engine.
+      # @return [NilClass]
       def clear_hydra_set_cache!
         [:@hydra_sets, :@hydra_set, :@hydra_set_ids, :@hydra_set_names].each do |variable|
           remove_instance_variable(variable) if instance_variable_defined?(variable)

data/lib/hydra_attribute/hydra_value_methods.rb

@@ -3,10 +3,17 @@ module HydraAttribute
     extend ActiveSupport::Concern
 
     module ClassMethods
+      # Clear cache
+      #
+      # @return [NilClass]
       def clear_hydra_value_cache!
       end
     end
 
+    # Returns the association instance for the given backend type attribute name
+    #
+    # @param backend_type [String] one of the HydraAttribute::SUPPORTED_BACKEND_TYPES values
+    # @return [ActiveRecord::Associations::Association]
     def hydra_value_association(backend_type)
       association(::HydraAttribute::AssociationBuilder.association_name(backend_type))
     end

data/lib/hydra_attribute/{memoize.rb → memoizable.rb}

@@ -1,5 +1,5 @@
 module HydraAttribute
-  module Memoize
+  module Memoizable
     def hydra_memoize(*methods)
       methods.each do |method_name|
         bound_method = instance_method(method_name)

data/lib/hydra_attribute/version.rb

@@ -1,3 +1,3 @@
 module HydraAttribute
-  VERSION = '0.4.0.rc1'
+  VERSION = '0.4.0.rc2'
 end

data/lib/hydra_attribute.rb

@@ -18,7 +18,7 @@ require 'hydra_attribute/configuration'
 require 'hydra_attribute/association_builder'
 require 'hydra_attribute/builder'
 require 'hydra_attribute/migrator'
-require 'hydra_attribute/memoize'
+require 'hydra_attribute/memoizable'
 require 'hydra_attribute/hydra_attribute'
 require 'hydra_attribute/hydra_set'
 require 'hydra_attribute/entity_callbacks'

data/spec/hydra_attribute/active_record/attribute_methods_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe HydraAttribute::ActiveRecord::AttributeMethods do
+  describe '::ClassMethods' do
+    describe '#define_hydra_attribute_method' do
+      it 'should throw MissingAttributeInHydraSetError if we call generated hydra attribute method which does not exist in hydra set' do
+        Product.hydra_attributes.create(name: 'color', backend_type: 'string')
+        hydra_set = Product.hydra_sets.create(name: 'Default')
+        product   = Product.new(hydra_set_id: hydra_set.id)
+
+        lambda do
+          product.color
+        end.should raise_error(HydraAttribute::MissingAttributeInHydraSetError, %(Hydra attribute "color" does not exist in hydra set "Default"))
+      end
+    end
+  end
+end