diff options
Diffstat (limited to 'activemodel/lib/active_model')
| -rw-r--r-- | activemodel/lib/active_model/attribute_methods.rb | 54 | ||||
| -rw-r--r-- | activemodel/lib/active_model/callbacks.rb | 14 | ||||
| -rw-r--r-- | activemodel/lib/active_model/conversion.rb | 18 | ||||
| -rw-r--r-- | activemodel/lib/active_model/dirty.rb | 17 | ||||
| -rw-r--r-- | activemodel/lib/active_model/errors.rb | 24 | ||||
| -rw-r--r-- | activemodel/lib/active_model/lint.rb | 6 | ||||
| -rw-r--r-- | activemodel/lib/active_model/locale/en.yml | 2 | ||||
| -rw-r--r-- | activemodel/lib/active_model/naming.rb | 8 | ||||
| -rw-r--r-- | activemodel/lib/active_model/observing.rb | 4 | ||||
| -rw-r--r-- | activemodel/lib/active_model/serialization.rb | 2 | ||||
| -rw-r--r-- | activemodel/lib/active_model/serializers/json.rb | 5 | ||||
| -rw-r--r-- | activemodel/lib/active_model/serializers/xml.rb | 3 | ||||
| -rw-r--r-- | activemodel/lib/active_model/translation.rb | 16 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validations.rb | 40 | ||||
| -rw-r--r-- | activemodel/lib/active_model/validator.rb | 5 |
15 files changed, 133 insertions, 85 deletions
diff --git a/activemodel/lib/active_model/attribute_methods.rb b/activemodel/lib/active_model/attribute_methods.rb index 7d0cdb5251..817640b178 100644 --- a/activemodel/lib/active_model/attribute_methods.rb +++ b/activemodel/lib/active_model/attribute_methods.rb @@ -4,12 +4,13 @@ require 'active_support/core_ext/class/inheritable_attributes' module ActiveModel class MissingAttributeError < NoMethodError end - + # == Active Model Attribute Methods + # # <tt>ActiveModel::AttributeMethods</tt> provides a way to add prefixes and suffixes # to your methods as well as handling the creation of Active Record like class methods # such as +table_name+. # - # The requirements to implement ActiveModel::AttributeMethods are: + # The requirements to implement ActiveModel::AttributeMethods are to: # # * <tt>include ActiveModel::AttributeMethods</tt> in your object # * Call each Attribute Method module method you want to add, such as @@ -45,24 +46,26 @@ module ActiveModel # end # end # - # Please notice that whenever you include ActiveModel::AttributeMethods in your class, - # it requires you to implement a <tt>attributes</tt> methods which returns a hash with - # each attribute name in your model as hash key and the attribute value as hash value. - # Hash keys must be a string. + # Notice that whenever you include ActiveModel::AttributeMethods in your class, + # it requires you to implement a <tt>attributes</tt> methods which returns a hash + # with each attribute name in your model as hash key and the attribute value as + # hash value. + # + # Hash keys must be strings. # module AttributeMethods extend ActiveSupport::Concern module ClassMethods - # Defines an "attribute" method (like +inheritance_column+ or - # +table_name+). A new (class) method will be created with the - # given name. If a value is specified, the new method will - # return that value (as a string). Otherwise, the given block - # will be used to compute the value of the method. + # Defines an "attribute" method (like +inheritance_column+ or +table_name+). + # A new (class) method will be created with the given name. If a value is + # specified, the new method will return that value (as a string). + # Otherwise, the given block will be used to compute the value of the + # method. # - # The original method will be aliased, with the new name being - # prefixed with "original_". This allows the new method to - # access the original value. + # The original method will be aliased, with the new name being prefixed + # with "original_". This allows the new method to access the original + # value. # # Example: # @@ -115,8 +118,8 @@ module ActiveModel # # #{prefix}attribute(#{attr}, *args, &block) # - # An <tt>#{prefix}attribute</tt> instance method must exist and accept at least - # the +attr+ argument. + # An instance method <tt>#{prefix}attribute</tt> must exist and accept + # at least the +attr+ argument. # # For example: # @@ -341,14 +344,17 @@ module ActiveModel end end - # Allows access to the object attributes, which are held in the <tt>@attributes</tt> hash, as though they - # were first-class methods. So a Person class with a name attribute can use Person#name and - # Person#name= and never directly use the attributes hash -- except for multiple assigns with - # ActiveRecord#attributes=. A Milestone class can also ask Milestone#completed? to test that - # the completed attribute is not +nil+ or 0. + # Allows access to the object attributes, which are held in the + # <tt>@attributes</tt> hash, as though they were first-class methods. So a + # Person class with a name attribute can use Person#name and Person#name= + # and never directly use the attributes hash -- except for multiple assigns + # with ActiveRecord#attributes=. A Milestone class can also ask + # Milestone#completed? to test that the completed attribute is not +nil+ + # or 0. # - # It's also possible to instantiate related objects, so a Client class belonging to the clients - # table with a +master_id+ foreign key can instantiate master through Client#master. + # It's also possible to instantiate related objects, so a Client class + # belonging to the clients table with a +master_id+ foreign key can + # instantiate master through Client#master. def method_missing(method_id, *args, &block) method_name = method_id.to_s if match = match_attribute_method?(method_name) @@ -367,7 +373,7 @@ module ActiveModel return true elsif !include_private_methods && super(method, true) # If we're here then we haven't found among non-private methods - # but found among all methods. Which means that given method is private. + # but found among all methods. Which means that the given method is private. return false elsif match_attribute_method?(method.to_s) return true diff --git a/activemodel/lib/active_model/callbacks.rb b/activemodel/lib/active_model/callbacks.rb index ad12600d7c..257644b3fa 100644 --- a/activemodel/lib/active_model/callbacks.rb +++ b/activemodel/lib/active_model/callbacks.rb @@ -2,7 +2,7 @@ require 'active_support/core_ext/array/wrap' require 'active_support/callbacks' module ActiveModel - # == Active Model Callbacks + # == Active Model Call Backs # # Provides an interface for any class to have Active Record like callbacks. # @@ -41,7 +41,7 @@ module ActiveModel # # Your code here # end # - # You can choose not to have all three callbacks by passing an hash to the + # You can choose not to have all three callbacks by passing a hash to the # define_model_callbacks method. # # define_model_callbacks :create, :only => :after, :before @@ -55,13 +55,13 @@ module ActiveModel end end - # define_model_callbacks accepts all options define_callbacks does, in case you - # want to overwrite a default. Besides that, it also accepts an :only option, + # define_model_callbacks accepts the same options define_callbacks does, in case + # you want to overwrite a default. Besides that, it also accepts an :only option, # where you can choose if you want all types (before, around or after) or just some. # # define_model_callbacks :initializer, :only => :after # - # Note, the <tt>:only => <type></tt> hash will apply to all callbacks defined on + # Note, the <tt>:only => <type></tt> hash will apply to all call backs defined on # that method call. To get around this you can call the define_model_callbacks # method as many times as you need. # @@ -73,7 +73,7 @@ module ActiveModel # # You can pass in a class to before_<type>, after_<type> and around_<type>, in which # case the call back will call that class's <action>_<type> method passing the object - # that the callback is being called on. + # that the call back is being called on. # # class MyModel # extend ActiveModel::Callbacks @@ -84,7 +84,7 @@ module ActiveModel # # class AnotherClass # def self.before_create( obj ) - # # obj is the MyModel instance that the callback is being called on + # # obj is the MyModel instance that the call back is being called on # end # end # diff --git a/activemodel/lib/active_model/conversion.rb b/activemodel/lib/active_model/conversion.rb index 23724b2d95..2a1650faa9 100644 --- a/activemodel/lib/active_model/conversion.rb +++ b/activemodel/lib/active_model/conversion.rb @@ -1,5 +1,7 @@ module ActiveModel - # Handle default conversions: to_model, to_key and to_param. + # == Active Model Conversions + # + # Handles default conversions: to_model, to_key and to_param. # # == Example # @@ -20,17 +22,19 @@ module ActiveModel # cm.to_param #=> nil # module Conversion - # If your object is already designed to implement all of the Active Model you can use - # the default to_model implementation, which simply returns self. + # If your object is already designed to implement all of the Active Model + # you can use the default to_model implementation, which simply returns + # self. # - # If your model does not act like an Active Model object, then you should define - # <tt>:to_model</tt> yourself returning a proxy object that wraps your object - # with Active Model compliant methods. + # If your model does not act like an Active Model object, then you should + # define <tt>:to_model</tt> yourself returning a proxy object that wraps + # your object with Active Model compliant methods. def to_model self end - # Returns an Enumerable of all (primary) key attributes or nil if persisted? is false + # Returns an Enumerable of all (primary) key attributes or nil if + # persisted? is false def to_key persisted? ? [id] : nil end diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb index bbcc345e4b..a82ce1bee0 100644 --- a/activemodel/lib/active_model/dirty.rb +++ b/activemodel/lib/active_model/dirty.rb @@ -4,16 +4,21 @@ require 'active_support/hash_with_indifferent_access' require 'active_support/core_ext/object/duplicable' module ActiveModel - # <tt>ActiveModel::Dirty</tt> provides a way to track changes in your - # object in the same way as ActiveRecord does. + # == Active Model Call Backs + # + # Provides a way to track changes in your object in the same way as + # Active Record does. # - # The requirements to implement ActiveModel::Dirty are: + # The requirements to implement ActiveModel::Dirty are to: # # * <tt>include ActiveModel::Dirty</tt> in your object - # * Call <tt>define_attribute_methods</tt> passing each method you want to track - # * Call <tt>attr_name_will_change!</tt> before each change to the tracked attribute + # * Call <tt>define_attribute_methods</tt> passing each method you want to + # track + # * Call <tt>attr_name_will_change!</tt> before each change to the tracked + # attribute # - # If you wish to also track previous changes on save or update, you need to add + # If you wish to also track previous changes on save or update, you need to + # add # # @previously_changed = changes # diff --git a/activemodel/lib/active_model/errors.rb b/activemodel/lib/active_model/errors.rb index 5c076d9d2f..9efb683547 100644 --- a/activemodel/lib/active_model/errors.rb +++ b/activemodel/lib/active_model/errors.rb @@ -6,6 +6,8 @@ require 'active_support/core_ext/object/blank' require 'active_support/ordered_hash' module ActiveModel + # == Active Model Errors + # # Provides a modified +OrderedHash+ that you can include in your object # for handling error messages and interacting with Action Pack helpers. # @@ -74,7 +76,8 @@ module ActiveModel alias_method :get, :[] alias_method :set, :[]= - # When passed a symbol or a name of a method, returns an array of errors for the method. + # When passed a symbol or a name of a method, returns an array of errors + # for the method. # # p.errors[:name] #=> ["can not be nil"] # p.errors['name'] #=> ["can not be nil"] @@ -234,15 +237,20 @@ module ActiveModel full_messages end - # Translates an error message in its default scope (<tt>activemodel.errors.messages</tt>). - # Error messages are first looked up in <tt>models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>, if it's not there, - # it's looked up in <tt>models.MODEL.MESSAGE</tt> and if that is not there it returns the translation of the - # default message (e.g. <tt>activemodel.errors.messages.MESSAGE</tt>). The translated model name, + # Translates an error message in its default scope + # (<tt>activemodel.errors.messages</tt>). + # + # Error messages are first looked up in <tt>models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>, + # if it's not there, it's looked up in <tt>models.MODEL.MESSAGE</tt> and if that is not + # there also, it returns the translation of the default message + # (e.g. <tt>activemodel.errors.messages.MESSAGE</tt>). The translated model name, # translated attribute name and the value are available for interpolation. # - # When using inheritance in your models, it will check all the inherited models too, but only if the model itself - # hasn't been found. Say you have <tt>class Admin < User; end</tt> and you wanted the translation for the <tt>:blank</tt> - # error +message+ for the <tt>title</tt> +attribute+, it looks for these translations: + # When using inheritance in your models, it will check all the inherited + # models too, but only if the model itself hasn't been found. Say you have + # <tt>class Admin < User; end</tt> and you wanted the translation for + # the <tt>:blank</tt> error +message+ for the <tt>title</tt> +attribute+, + # it looks for these translations: # # <ol> # <li><tt>activemodel.errors.models.admin.attributes.title.blank</tt></li> diff --git a/activemodel/lib/active_model/lint.rb b/activemodel/lib/active_model/lint.rb index 13ddb622d1..a5977bf3cc 100644 --- a/activemodel/lib/active_model/lint.rb +++ b/activemodel/lib/active_model/lint.rb @@ -1,5 +1,7 @@ -# You can test whether an object is compliant with the ActiveModel API by -# including ActiveModel::Lint::Tests in your TestCase. It will included +# == Active Model Lint Tests +# +# You can test whether an object is compliant with the Active Model API by +# including <tt>ActiveModel::Lint::Tests</tt> in your TestCase. It will include # tests that tell you whether your object is fully compliant, or if not, # which aspects of the API are not implemented. # diff --git a/activemodel/lib/active_model/locale/en.yml b/activemodel/lib/active_model/locale/en.yml index 602a530dc0..44425b4a28 100644 --- a/activemodel/lib/active_model/locale/en.yml +++ b/activemodel/lib/active_model/locale/en.yml @@ -1,6 +1,6 @@ en: errors: - # The default format use in full error messages. + # The default format to use in full error messages. format: "%{attribute} %{message}" # The values :model, :attribute and :value are always available for interpolation diff --git a/activemodel/lib/active_model/naming.rb b/activemodel/lib/active_model/naming.rb index 8cdd3d2fe8..ca1e9f0ee8 100644 --- a/activemodel/lib/active_model/naming.rb +++ b/activemodel/lib/active_model/naming.rb @@ -1,7 +1,6 @@ require 'active_support/inflector' module ActiveModel - class Name < String attr_reader :singular, :plural, :element, :collection, :partial_path alias_method :cache_key, :collection @@ -36,8 +35,9 @@ module ActiveModel end end - # ActiveModel::Naming is a module that creates a +model_name+ method on your - # object. + # == Active Model Naming + # + # Creates a +model_name+ method on your object. # # To implement, just extend ActiveModel::Naming in your object: # @@ -49,7 +49,7 @@ module ActiveModel # BookCover.model_name.human #=> "Book cover" # # Providing the functionality that ActiveModel::Naming provides in your object - # is required to pass the ActiveModel Lint test. So either extending the provided + # is required to pass the Active Model Lint test. So either extending the provided # method below, or rolling your own is required.. module Naming # Returns an ActiveModel::Name object for module. It can be diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb index d7e3ca100e..14f8bf72dc 100644 --- a/activemodel/lib/active_model/observing.rb +++ b/activemodel/lib/active_model/observing.rb @@ -9,6 +9,8 @@ module ActiveModel extend ActiveSupport::Concern module ClassMethods + # == Active Model Observers Activation + # # Activates the observers assigned. Examples: # # # Calls PersonObserver.instance @@ -89,6 +91,8 @@ module ActiveModel end end + # == Active Model Observers + # # Observer classes respond to lifecycle callbacks to implement trigger-like # behavior outside the original class. This is a great way to reduce the # clutter that normally comes when the model class is burdened with diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb index 1c48d4613a..5670ec74cb 100644 --- a/activemodel/lib/active_model/serialization.rb +++ b/activemodel/lib/active_model/serialization.rb @@ -2,6 +2,8 @@ require 'active_support/core_ext/hash/except' require 'active_support/core_ext/hash/slice' module ActiveModel + # == Active Model Serialization + # # Provides a basic serialization to a serializable_hash for your object. # # A minimal implementation could be: diff --git a/activemodel/lib/active_model/serializers/json.rb b/activemodel/lib/active_model/serializers/json.rb index 90305978c4..918cd0ab76 100644 --- a/activemodel/lib/active_model/serializers/json.rb +++ b/activemodel/lib/active_model/serializers/json.rb @@ -2,6 +2,7 @@ require 'active_support/json' require 'active_support/core_ext/class/attribute' module ActiveModel + # == Active Model JSON Serializer module Serializers module JSON extend ActiveSupport::Concern @@ -14,8 +15,8 @@ module ActiveModel self.include_root_in_json = true end - # Returns a JSON string representing the model. Some configuration is - # available through +options+. + # Returns a JSON string representing the model. Some configuration can be + # passed through +options+. # # The option <tt>ActiveModel::Base.include_root_in_json</tt> controls the # top-level behavior of to_json. It is true by default. When it is <tt>true</tt>, diff --git a/activemodel/lib/active_model/serializers/xml.rb b/activemodel/lib/active_model/serializers/xml.rb index 934af2b8a8..ed64434b8f 100644 --- a/activemodel/lib/active_model/serializers/xml.rb +++ b/activemodel/lib/active_model/serializers/xml.rb @@ -5,6 +5,7 @@ require 'active_support/core_ext/hash/conversions' require 'active_support/core_ext/hash/slice' module ActiveModel + # == Active Model XML Serializer module Serializers module Xml extend ActiveSupport::Concern @@ -131,6 +132,8 @@ module ActiveModel end end + # Returns XML representing the model. Configuration can be + # passed through +options+. def to_xml(options = {}, &block) Serializer.new(self, options).serialize(&block) end diff --git a/activemodel/lib/active_model/translation.rb b/activemodel/lib/active_model/translation.rb index 15d0c7ddb1..0554677296 100644 --- a/activemodel/lib/active_model/translation.rb +++ b/activemodel/lib/active_model/translation.rb @@ -1,9 +1,11 @@ require 'active_support/core_ext/hash/reverse_merge' module ActiveModel - - # ActiveModel::Translation provides integration between your object and - # the Rails internationalization (i18n) framework. + + # == Active Model Translation + # + # Provides integration between your object and the Rails internationalization + # (i18n) framework. # # A minimal implementation could be: # @@ -26,14 +28,16 @@ module ActiveModel :activemodel end - # When localizing a string, goes through the lookup returned by this method. - # Used in ActiveModel::Name#human, ActiveModel::Errors#full_messages and + # When localizing a string, it goes through the lookup returned by this + # method, which is used in ActiveModel::Name#human, + # ActiveModel::Errors#full_messages and # ActiveModel::Translation#human_attribute_name. def lookup_ancestors self.ancestors.select { |x| x.respond_to?(:model_name) } end - # Transforms attributes names into a more human format, such as "First name" instead of "first_name". + # Transforms attribute names into a more human format, such as "First name" + # instead of "first_name". # # Person.human_attribute_name("first_name") # => "First name" # diff --git a/activemodel/lib/active_model/validations.rb b/activemodel/lib/active_model/validations.rb index 173891bcda..36d89c2492 100644 --- a/activemodel/lib/active_model/validations.rb +++ b/activemodel/lib/active_model/validations.rb @@ -5,7 +5,9 @@ require 'active_support/core_ext/hash/keys' require 'active_model/errors' module ActiveModel - + + # == Active Model Validations + # # Provides a full validation framework to your objects. # # A minimal implementation could be: @@ -38,7 +40,7 @@ module ActiveModel # # Note that ActiveModel::Validations automatically adds an +errors+ method # to your instances initialized with a new ActiveModel::Errors object, so - # there is no need for you to add this manually. + # there is no need for you to do this manually. # module Validations extend ActiveSupport::Concern @@ -71,14 +73,14 @@ module ActiveModel # end # # Options: - # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, - # other options <tt>:create</tt>, <tt>:update</tt>). + # * <tt>:on</tt> - Specifies when this validation is active (default is + # <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>). # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+. # * <tt>:allow_blank</tt> - Skip validation if attribute is blank. - # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should - # occur (e.g. <tt>:if => :allow_validation</tt>, or - # <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The - # method, proc or string should return or evaluate to a true or false value. + # * <tt>:if</tt> - Specifies a method, proc or string to call to determine + # if the validation should occur (e.g. <tt>:if => :allow_validation</tt>, + # or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, + # proc or string should return or evaluate to a true or false value. # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should # not occur (e.g. <tt>:unless => :skip_validation</tt>, or # <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The @@ -104,7 +106,7 @@ module ActiveModel # end # end # - # Or with a block which is passed the current record to be validated: + # Or with a block which is passed with the current record to be validated: # # class Comment # include ActiveModel::Validations @@ -127,7 +129,8 @@ module ActiveModel set_callback(:validate, *args, &block) end - # List all validators that being used to validate the model using +validates_with+ method. + # List all validators that are being used to validate the model using + # +validates_with+ method. def validators _validators.values.flatten.uniq end @@ -155,9 +158,9 @@ module ActiveModel @errors ||= Errors.new(self) end - # Runs all the specified validations and returns true if no errors were added otherwise false. - # Context can optionally be supplied to define which callbacks to test against (the context is - # defined on the validations using :on). + # Runs all the specified validations and returns true if no errors were added + # otherwise false. Context can optionally be supplied to define which callbacks + # to test against (the context is defined on the validations using :on). def valid?(context = nil) current_context, self.validation_context = validation_context, context errors.clear @@ -167,14 +170,17 @@ module ActiveModel self.validation_context = current_context end - # Performs the opposite of <tt>valid?</tt>. Returns true if errors were added, false otherwise. + # Performs the opposite of <tt>valid?</tt>. Returns true if errors were added, + # false otherwise. def invalid?(context = nil) !valid?(context) end - # Hook method defining how an attribute value should be retrieved. By default this is assumed - # to be an instance named after the attribute. Override this method in subclasses should you - # need to retrieve the value for a given attribute differently e.g. + # Hook method defining how an attribute value should be retrieved. By default + # this is assumed to be an instance named after the attribute. Override this + # method in subclasses should you need to retrieve the value for a given + # attribute differently: + # # class MyClass # include ActiveModel::Validations # diff --git a/activemodel/lib/active_model/validator.rb b/activemodel/lib/active_model/validator.rb index 114e9091bc..689c617177 100644 --- a/activemodel/lib/active_model/validator.rb +++ b/activemodel/lib/active_model/validator.rb @@ -3,6 +3,9 @@ require "active_support/core_ext/module/anonymous" require 'active_support/core_ext/object/blank' module ActiveModel #:nodoc: + + # == Active Model Validator + # # A simple base class that can be used along with # +ActiveModel::Validations::ClassMethods.validates_with+ # @@ -127,7 +130,7 @@ module ActiveModel #:nodoc: # in the options hash invoking the validate_each method passing in the # record, attribute and value. # - # All ActiveModel validations are built on top of this Validator. + # All Active Model validations are built on top of this Validator. class EachValidator < Validator attr_reader :attributes |