From 76dc58b4d098a8db13c87e07444e3fed8643fbb4 Mon Sep 17 00:00:00 2001 From: claudiob Date: Wed, 7 Jan 2015 09:05:23 -0800 Subject: [PATCH] Better docs for AM::Lint::Tests This commit changes the original documentation of ActiveModel::Lint::Tests introduced in dbf20c2d to focus less on *why* the tests exist and more on *what* the tests do. For instance, `test_to_key` was documented as: > Returns an Enumerable of all (primary) key attributes... whereas `test_to_key` is simply a test meant to *fail* or *pass*, and the documentation above refers to `to_key`. [ci skip] --- activemodel/lib/active_model/lint.rb | 60 +++++++++++++++------------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/activemodel/lib/active_model/lint.rb b/activemodel/lib/active_model/lint.rb index 38087521a2..010eaeb170 100644 --- a/activemodel/lib/active_model/lint.rb +++ b/activemodel/lib/active_model/lint.rb @@ -21,28 +21,27 @@ module ActiveModel # +self+. module Tests - # == Responds to to_key + # Passes if the object's model responds to to_key and if calling + # this method returns +nil+ when the object is not persisted. + # Fails otherwise. # - # Returns an Enumerable of all (primary) key attributes - # or nil if model.persisted? is false. This is used by - # dom_id to generate unique ids for the object. + # to_key returns an Enumerable of all (primary) key attributes + # of the model, and is used to a generate unique DOM id for the object. def test_to_key assert model.respond_to?(:to_key), "The model should respond to to_key" def model.persisted?() false end assert model.to_key.nil?, "to_key should return nil when `persisted?` returns false" end - # == Responds to to_param - # - # Returns a string representing the object's key suitable for use in URLs - # or +nil+ if model.persisted? is +false+. + # Passes if the object's model responds to to_param and if + # calling this method returns +nil+ when the object is not persisted. + # Fails otherwise. # + # to_param is used to represent the object's key in URLs. # Implementers can decide to either raise an exception or provide a # default in case the record uses a composite primary key. There are no # tests for this behavior in lint because it doesn't make sense to force # any of the possible implementation strategies on the implementer. - # However, if the resource is not persisted?, then to_param - # should always return +nil+. def test_to_param assert model.respond_to?(:to_param), "The model should respond to to_param" def model.to_key() [1] end @@ -50,32 +49,34 @@ module ActiveModel assert model.to_param.nil?, "to_param should return nil when `persisted?` returns false" end - # == Responds to to_partial_path + # Passes if the object's model responds to to_partial_path and if + # calling this method returns a string. Fails otherwise. # - # Returns a string giving a relative path. This is used for looking up - # partials. For example, a BlogPost model might return "blog_posts/blog_post" + # to_partial_path is used for looking up partials. For example, + # a BlogPost model might return "blog_posts/blog_post". def test_to_partial_path assert model.respond_to?(:to_partial_path), "The model should respond to to_partial_path" assert_kind_of String, model.to_partial_path end - # == Responds to persisted? + # Passes if the object's model responds to persisted? and if + # calling this method returns either +true+ or +false+. Fails otherwise. # - # Returns a boolean that specifies whether the object has been persisted - # yet. This is used when calculating the URL for an object. If the object - # is not persisted, a form for that object, for instance, will route to - # the create action. If it is persisted, a form for the object will routes - # to the update action. + # persisted? is used when calculating the URL for an object. + # If the object is not persisted, a form for that object, for instance, + # will route to the create action. If it is persisted, a form for the + # object will route to the update action. def test_persisted? assert model.respond_to?(:persisted?), "The model should respond to persisted?" assert_boolean model.persisted?, "persisted?" end - # == \Naming + # Passes if the object's model responds to model_name both as + # an instance method and as a class method, and if calling this method + # returns a string with some convenience methods: :human, + # :singular and :plural. # - # Model.model_name and Model#model_name must return a string with some - # convenience methods: # :human, :singular and - # :plural. Check ActiveModel::Naming for more information. + # Check ActiveModel::Naming for more information. def test_model_naming assert model.class.respond_to?(:model_name), "The model class should respond to model_name" model_name = model.class.model_name @@ -88,12 +89,15 @@ module ActiveModel assert_equal model.model_name, model.class.model_name end - # == \Errors Testing + # Passes if the object's model responds to errors and if calling + # [](attribute) on the result of this method returns an array. + # Fails otherwise. # - # Returns an object that implements [](attribute) defined which returns an - # Array of Strings that are the errors for the attribute in question. - # If localization is used, the Strings should be localized for the current - # locale. If no error is present, this method should return an empty Array. + # errors[attribute] is used to retrieve the errors of a model + # for a given attribute. If errors are present, the method should return + # an array of strings that are the errors for the attribute in question. + # If localization is used, the strings should be localized for the current + # locale. If no error is present, the method should return an empty array. def test_errors_aref assert model.respond_to?(:errors), "The model should respond to errors" assert model.errors[:hello].is_a?(Array), "errors#[] should return an Array"