@@ -1,5 +1,7 @@ *SVN* +* Improve documentation. [Xavier Noria, leethal, jerome] + * Ensure RJS redirect_to doesn't html-escapes string argument. Closes #8546 [josh, eventualbuddha, Pratik] * Support render :partial => collection of heterogeneous elements. #11491 [Zach Dennis] actionpack/CHANGELOG @@ -47,7 +47,7 @@ module ActionController # :controller maps to your controller name # :action maps to an action with your controllers # - # Other names simply map to a parameter as in the case of +:id+. + # Other names simply map to a parameter as in the case of <tt>:id</tt>. # # == Route priority # @@ -82,7 +82,7 @@ module ActionController # This sets up +blog+ as the default controller if no other is specified. # This means visiting '/' would invoke the blog controller. # - # More formally, you can define defaults in a route with the +:defaults+ key. + # More formally, you can define defaults in a route with the <tt>:defaults</tt> key. # # map.connect ':controller/:action/:id', :action => 'show', :defaults => { :page => 'Dashboard' } # actionpack/lib/action_controller/routing.rb @@ -716,11 +716,11 @@ module ActionView # # Insert the rendered 'navigation' partial just before the DOM # # element with ID 'content'. # # Generates: new Insertion.Before("content", "-- Contents of 'navigation' partial --"); - # insert_html :before, 'content', :partial => 'navigation' + # page.insert_html :before, 'content', :partial => 'navigation' # # # Add a list item to the bottom of the <ul> with ID 'list'. # # Generates: new Insertion.Bottom("list", "<li>Last item</li>"); - # insert_html :bottom, 'list', '<li>Last item</li>' + # page.insert_html :bottom, 'list', '<li>Last item</li>' # def insert_html(position, id, *options_for_render) insertion = position.to_s.camelize @@ -735,7 +735,7 @@ module ActionView # # Replace the HTML of the DOM element having ID 'person-45' with the # # 'person' partial for the appropriate object. # # Generates: Element.update("person-45", "-- Contents of 'person' partial --"); - # replace_html 'person-45', :partial => 'person', :object => @person + # page.replace_html 'person-45', :partial => 'person', :object => @person # def replace_html(id, *options_for_render) call 'Element.update', id, render(*options_for_render) @@ -749,7 +749,7 @@ module ActionView # # # Replace the DOM element having ID 'person-45' with the # # 'person' partial for the appropriate object. - # replace 'person-45', :partial => 'person', :object => @person + # page.replace 'person-45', :partial => 'person', :object => @person # # This allows the same partial that is used for the +insert_html+ to # be also used for the input to +replace+ without resorting to actionpack/lib/action_view/helpers/prototype_helper.rb @@ -86,7 +86,7 @@ module ActionView # of +options+. See the valid options in the documentation for # url_for. It's also possible to pass a string instead # of an options hash to get a link tag that uses the value of the string as the - # href for the link, or use +:back+ to link to the referrer - a JavaScript back + # href for the link, or use <tt>:back</tt> to link to the referrer - a JavaScript back # link will be used in place of a referrer if none exists. If nil is passed as # a name, the link itself will become the name. # actionpack/lib/action_view/helpers/url_helper.rb @@ -1,5 +1,7 @@ *SVN* +* Improve documentation. [Xavier Noria, Jack Danger Canty, leethal] + * Tweak ActiveRecord::Base#to_json to include a root value in the returned hash: {"post": {"title": ...}} [rick] Post.find(1).to_json # => {"title": ...} activerecord/CHANGELOG @@ -102,21 +102,14 @@ A short rundown of the major features: {Learn more}[link:classes/ActiveRecord/Base.html] -* Transaction support on both a database and object level. The latter is implemented - by using Transaction::Simple[http://railsmanual.com/module/Transaction::Simple] +* Transactions - # Just database transaction + # Database transaction Account.transaction do david.withdrawal(100) mary.deposit(100) end - # Database and object transaction - Account.transaction(david, mary) do - david.withdrawal(100) - mary.deposit(100) - end - {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html] activerecord/README @@ -136,7 +136,7 @@ module ActiveRecord # #others.create!(attributes={}) | X | X | X # #others.size | X | X | X # #others.length | X | X | X - # #others.count | | X | X + # #others.count | X | X | X # #others.sum(args*,&block) | X | X | X # #others.empty? | X | X | X # #others.clear | X | X | @@ -150,9 +150,9 @@ module ActiveRecord # # == Cardinality and associations # - # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many - # and many-to-many cardinality. Each model uses an association to describe its role in - # the relation. In each case, the +belongs_to+ association is used in the model that has + # ActiveRecord associations can be used to describe one-to-one, one-to-many and many-to-many + # relationships between models. Each model uses an association to describe its role in + # the relation. The +belongs_to+ association is always used in the model that has # the foreign key. # # === One-to-one activerecord/lib/active_record/associations.rb @@ -1,5 +1,50 @@ module ActiveRecord module Associations + # This is the root class of all association proxies: + # + # AssociationProxy + # BelongsToAssociation + # HasOneAssociation + # BelongsToPolymorphicAssociation + # AssociationCollection + # HasManyAssociation + # HasAndBelongsToManyAssociation + # HasManyThroughAssociation + # HasOneThroughAssociation + # + # Association proxies in Active Record are middlemen between the object that + # holds the association, known as the <tt>@owner</tt>, and the actual associated + # object, known as the <tt>@target</tt>. The kind of association any proxy is + # about is available in <tt>@reflection</tt>. That's an instance of the class + # ActiveRecord::Reflection::AssociationReflection. + # + # For example, given + # + # class Blog < ActiveRecord::Base + # has_many :posts + # end + # + # blog = Blog.find(:first) + # + # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as + # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and + # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro. + # + # This class has most of the basic instance methods removed, and delegates + # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a + # corner case, it even removes the +class+ method and that's why you get + # + # blog.posts.class # => Array + # + # though the object behind <tt>blog.posts</tt> is not an Array, but an + # ActiveRecord::Associations::HasManyAssociation. + # + # The <tt>@target</tt> object is not loaded until needed. For example, + # + # blog.posts.count + # + # is computed directly through SQL and does not trigger by itself the + # instantiation of the actual post records. class AssociationProxy #:nodoc: alias_method :proxy_respond_to?, :respond_to? alias_method :proxy_extend, :extend activerecord/lib/active_record/associations/association_proxy.rb @@ -191,6 +191,10 @@ module ActiveRecord #:nodoc: # # Student.find(:all, :conditions => { :grade => 9..12 }) # + # An array may be used in the hash to use the SQL IN operator: + # + # Student.find(:all, :conditions => { :grade => [9,11,12] }) + # # == Overwriting default accessors # # All column values are automatically available through basic accessors on the Active Record object, but sometimes you @@ -488,6 +492,7 @@ module ActiveRecord #:nodoc: # Examples for find all: # Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people # Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50) + # Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] } # Person.find(:all, :offset => 10, :limit => 10) # Person.find(:all, :include => [ :account, :friends ]) # Person.find(:all, :group => "category") activerecord/lib/active_record/base.rb @@ -161,12 +161,12 @@ module ActiveRecord # an Array of Symbols. # # The index will be named after the table and the first column name, - # unless you pass +:name+ as an option. + # unless you pass <tt>:name</tt> as an option. # # When creating an index on multiple columns, the first column is used as a name # for the index. For example, when you specify an index on two columns - # [+:first+, +:last+], the DBMS creates an index for both columns as well as an - # index for the first column +:first+. Using just the first name for this index + # [<tt>:first</tt>, <tt>:last</tt>], the DBMS creates an index for both columns as well as an + # index for the first column <tt>:first</tt>. Using just the first name for this index # makes sense, because you will never have to create a singular index with this # name. # activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -76,34 +76,39 @@ module ActiveRecord @macro, @name, @options, @active_record = macro, name, options, active_record end - # Returns the name of the macro, so it would return :balance for "composed_of :balance, :class_name => 'Money'" or - # :clients for "has_many :clients". + # Returns the name of the macro. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return + # <tt>:balance</tt> or for <tt>has_many :clients</tt> it will return <tt>:clients</tt>. def name @name end - # Returns the type of the macro, so it would return :composed_of for - # "composed_of :balance, :class_name => 'Money'" or :has_many for "has_many :clients". + # Returns the macro type. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt> + # or for <tt>has_many :clients</tt> will return <tt>:has_many</tt>. def macro @macro end - # Returns the hash of options used for the macro, so it would return { :class_name => "Money" } for - # "composed_of :balance, :class_name => 'Money'" or {} for "has_many :clients". + # Returns the hash of options used for the macro. For example, it would return <tt>{ :class_name => "Money" }</tt> for + # <tt>composed_of :balance, :class_name => 'Money'</tt> or +{}+ for <tt>has_many :clients</tt>. + def options @options end - # Returns the class for the macro, so "composed_of :balance, :class_name => 'Money'" returns the Money class and - # "has_many :clients" returns the Client class. + # Returns the class for the macro. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the +Money+ + # class and <tt>has_many :clients</tt> returns the +Client+ class. def klass @klass ||= class_name.constantize end + # Returns the class name for the macro. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns <tt>'Money'</tt> + # and <tt>has_many :clients</tt> returns <tt>'Client'</tt>. def class_name @class_name ||= options[:class_name] || derive_class_name end + # Returns +true+ if +self+ and +other_aggregation+ have the same +name+ attribute, +active_record+ attribute, + # and +other_aggregation+ has an options hash assigned to it. def ==(other_aggregation) name == other_aggregation.name && other_aggregation.options && active_record == other_aggregation.active_record end activerecord/lib/active_record/reflection.rb @@ -28,7 +28,7 @@ module ActiveRecord # # This example will only take money from David and give to Mary if neither +withdrawal+ nor +deposit+ raises an exception. # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though, - # that the objects by default will _not_ have their instance data returned to their pre-transactional state. + # that the objects will _not_ have their instance data returned to their pre-transactional state. # # == Different ActiveRecord classes in a single transaction # activerecord/lib/active_record/transactions.rb @@ -723,7 +723,7 @@ module ActiveRecord # # Configuration options: # * <tt>in</tt> - An enumerable object of available items - # * <tt>message</tt> - Specifies a customer error message (default is: "is not included in the list") + # * <tt>message</tt> - Specifies a custom error message (default is: "is not included in the list") # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false) # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false) # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should @@ -755,7 +755,7 @@ module ActiveRecord # # Configuration options: # * <tt>in</tt> - An enumerable object of items that the value shouldn't be part of - # * <tt>message</tt> - Specifies a customer error message (default is: "is reserved") + # * <tt>message</tt> - Specifies a custom error message (default is: "is reserved") # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false) # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false) # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should activerecord/lib/active_record/validations.rb @@ -1,5 +1,7 @@ *SVN* +* Improve documentation. [Xavier Noria] + * Fixed that to_param should be used and honored instead of hardcoding the id #11406 [gspiers] * Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria, Sunny Ripert] activeresource/CHANGELOG @@ -3,9 +3,8 @@ module ActiveSupport #:nodoc: module Array #:nodoc: # Makes it easier to access parts of an array. module Access - # Returns the remaining of the array from the +position+. + # Returns the tail of the array from +position+. # - # Examples: # %w( a b c d ).from(0) # => %w( a b c d ) # %w( a b c d ).from(2) # => %w( c d ) # %w( a b c d ).from(10) # => nil @@ -13,9 +12,8 @@ module ActiveSupport #:nodoc: self[position..-1] end - # Returns the beginning of the array up to the +position+. + # Returns the beginning of the array up to +position+. # - # Examples: # %w( a b c d ).to(0) # => %w( a ) # %w( a b c d ).to(2) # => %w( a b c ) # %w( a b c d ).to(10) # => %w( a b c d ) activesupport/lib/active_support/core_ext/array/access.rb @@ -30,10 +30,8 @@ module ActiveSupport #:nodoc: map(&:to_param).join '/' end - # Converts an array into a string suitable for use as a URL query string, using the given <tt>key</tt> as the - # param name. - # - # Example: + # Converts an array into a string suitable for use as a URL query string, + # using the given +key+ as the param name. # # ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding" def to_query(key) @@ -81,8 +79,6 @@ module ActiveSupport #:nodoc: # # Root children have as node name the one of the root singularized. # - # Example: - # # [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml # # <?xml version="1.0" encoding="UTF-8"?> activesupport/lib/active_support/core_ext/array/conversions.rb @@ -2,7 +2,8 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Array #:nodoc: module ExtractOptions - # Extract options from a set of arguments. Removes and returns the last element in the array if it's a hash, otherwise returns a blank hash. + # Extracts options from a set of arguments. Removes and returns the last + # element in the array if it's a hash, otherwise returns a blank hash. # # def options(*args) # args.extract_options! activesupport/lib/active_support/core_ext/array/extract_options.rb @@ -4,11 +4,8 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Array #:nodoc: module Grouping - # Iterate over an array in groups of a certain size, padding any remaining - # slots with specified value (<tt>nil</tt> by default) unless it is - # <tt>false</tt>. - # - # Examples: + # Iterates over the array in groups of size +number+, padding any remaining + # slots with +fill_with+ unless it is +false+. # # %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g} # ["1", "2", "3"] @@ -42,11 +39,9 @@ module ActiveSupport #:nodoc: end end - # Divide the array into one or more subarrays based on a delimiting +value+ + # Divides the array into one or more subarrays based on a delimiting +value+ # or the result of an optional block. # - # Examples: - # # [1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]] # (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]] def split(value = nil, &block) activesupport/lib/active_support/core_ext/array/grouping.rb @@ -2,7 +2,7 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Array #:nodoc: module RandomAccess - # Return a random element from the array. + # Returns a random element from the array. def rand self[Kernel.rand(length)] end activesupport/lib/active_support/core_ext/array/random_access.rb @@ -1,10 +1,13 @@ class Object # An object is blank if it's false, empty, or a whitespace string. - # For example, "", " ", nil, [], and {} are blank. + # For example, "", " ", +nil+, [], and {} are blank. # # This simplifies + # # if !address.nil? && !address.empty? + # # to + # # if !address.blank? def blank? respond_to?(:empty?) ? empty? : !self activesupport/lib/active_support/core_ext/blank.rb @@ -1,21 +1,38 @@ class Class #:nodoc: - # Will unassociate the class with its subclasses as well as uninitializing the subclasses themselves. - # >> Integer.remove_subclasses - # => [Bignum, Fixnum] - # >> Fixnum - # NameError: uninitialized constant Fixnum + # Unassociates the class with its subclasses and removes the subclasses + # themselves. + # + # Integer.remove_subclasses # => [Bignum, Fixnum] + # Fixnum # => NameError: uninitialized constant Fixnum def remove_subclasses Object.remove_subclasses_of(self) end - # Returns a list of classes that inherit from this class in an array. - # Example: Integer.subclasses => ["Bignum", "Fixnum"] + # Returns an array with the names of the subclasses of +self+ as strings. + # + # Integer.subclasses # => ["Bignum", "Fixnum"] def subclasses Object.subclasses_of(self).map { |o| o.to_s } end - # Allows you to remove individual subclasses or a selection of subclasses from a class without removing all of them. + # Removes the classes in +klasses+ from their parent module. + # + # Ordinary classes belong to some module via a constant. This method computes + # that constant name from the class name and removes it from the module it + # belongs to. + # + # Object.remove_class(Integer) # => [Integer] + # Integer # => NameError: uninitialized constant Integer + # + # Take into account that in general the class object could be still stored + # somewhere else. + # + # i = Integer # => Integer + # Object.remove_class(Integer) # => [Integer] + # Integer # => NameError: uninitialized constant Integer + # i.subclasses # => ["Bignum", "Fixnum"] + # Fixnum.superclass # => Integer def remove_class(*klasses) klasses.flatten.each do |klass| # Skip this class if there is nothing bound to this name activesupport/lib/active_support/core_ext/class/removal.rb @@ -16,12 +16,12 @@ module ActiveSupport #:nodoc: end module ClassMethods - # Finds yesterday's date, in the format similar to: Mon, 17 Mar 2008 + # Returns a new Date representing the date 1 day ago (i.e. yesterday's date). def yesterday ::Date.today.yesterday end - # Finds tommorrow's date, in the format similar to: Tue, 18 Mar 2008 + # Returns a new Date representing the date 1 day after today (i.e. tomorrow's date). def tomorrow ::Date.today.tomorrow end activesupport/lib/active_support/core_ext/date/calculations.rb @@ -45,7 +45,7 @@ module ActiveSupport #:nodoc: formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter) end - # Returns the utc_offset as an +HH:MM formatted string. Examples: + # Returns the +utc_offset+ as an +HH:MM formatted string. Examples: # # datetime = DateTime.civil(2000, 1, 1, 0, 0, 0, Rational(-6, 24)) # datetime.formatted_offset # => "-06:00" activesupport/lib/active_support/core_ext/date_time/conversions.rb @@ -3,12 +3,10 @@ module ActiveSupport #:nodoc: module Integer #:nodoc: # For checking if a fixnum is even or odd. # - # Examples: - # # 1.even? # => false # 1.odd? # => true # 2.even? # => true - # 2.odd? # => false + # 2.odd? # => false module EvenOdd def multiple_of?(number) self % number == 0 activesupport/lib/active_support/core_ext/integer/even_odd.rb @@ -7,8 +7,6 @@ module ActiveSupport #:nodoc: # Ordinalize turns a number into an ordinal string used to denote the # position in an ordered sequence such as 1st, 2nd, 3rd, 4th. # - # Examples: - # # 1.ordinalize # => "1st" # 2.ordinalize # => "2nd" # 1002.ordinalize # => "1002nd" activesupport/lib/active_support/core_ext/integer/inflections.rb @@ -37,7 +37,7 @@ class Object instance_variables.map(&:to_s) end - # Copies the instance variables of +object+ into self. + # Copies the instance variables of +object+ into +self+. # # Instance variable names in the +exclude+ array are ignored. If +object+ # responds to <tt>protected_instance_variables</tt> the ones returned are activesupport/lib/active_support/core_ext/object/instance_variables.rb @@ -10,11 +10,11 @@ module ActiveSupport #:nodoc: # string overrides can also be called through the +chars+ proxy. # # name = 'Claus Müller' - # name.reverse #=> "rell??M sualC" - # name.length #=> 13 + # name.reverse #=> "rell??M sualC" + # name.length #=> 13 # - # name.chars.reverse.to_s #=> "rellüM sualC" - # name.chars.length #=> 12 + # name.chars.reverse.to_s #=> "rellüM sualC" + # name.chars.length #=> 12 # # # All the methods on the chars proxy which normally return a string will return a Chars object. This allows activesupport/lib/active_support/core_ext/string/unicode.rb @@ -20,11 +20,10 @@ module ActiveSupport #:nodoc: end end - # Convert to a formatted string. See DATE_FORMATS for builtin formats. + # Converts to a formatted string. See DATE_FORMATS for builtin formats. # # This method is aliased to <tt>to_s</tt>. # - # ==== Examples: # time = Time.now # => Thu Jan 18 06:10:17 CST 2007 # # time.to_formatted_s(:time) # => "06:10:17" @@ -36,7 +35,7 @@ module ActiveSupport #:nodoc: # time.to_formatted_s(:long_ordinal) # => "January 18th, 2007 06:10" # time.to_formatted_s(:rfc822) # => "Thu, 18 Jan 2007 06:10:17 -0600" # - # == Adding your own time formats to to_formatted_s + # == Adding your own time formats to +to_formatted_s+ # You can add your own formats to the Time::DATE_FORMATS hash. # Use the format name as the hash key and either a strftime string # or Proc instance that takes a time argument as the value. @@ -49,7 +48,7 @@ module ActiveSupport #:nodoc: formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter) end - # Returns the utc_offset as an +HH:MM formatted string. Examples: + # Returns the UTC offset as an +HH:MM formatted string. # # Time.local(2000).formatted_offset # => "-06:00" # Time.local(2000).formatted_offset(false) # => "-0600" @@ -57,20 +56,13 @@ module ActiveSupport #:nodoc: utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon) end - # Convert a Time object to a Date, dropping hour, minute, and second precision. + # Converts a Time object to a Date, dropping hour, minute, and second precision. # - # ==== Examples - # my_time = Time.now - # # => Mon Nov 12 22:59:51 -0500 2007 + # my_time = Time.now # => Mon Nov 12 22:59:51 -0500 2007 + # my_time.to_date #=> Mon, 12 Nov 2007 # - # my_time.to_date - # #=> Mon, 12 Nov 2007 - # - # your_time = Time.parse("1/13/2009 1:13:03 P.M.") - # # => Tue Jan 13 13:13:03 -0500 2009 - # - # your_time.to_date - # # => Tue, 13 Jan 2009 + # your_time = Time.parse("1/13/2009 1:13:03 P.M.") # => Tue Jan 13 13:13:03 -0500 2009 + # your_time.to_date # => Tue, 13 Jan 2009 def to_date ::Date.new(year, month, day) end @@ -83,18 +75,11 @@ module ActiveSupport #:nodoc: # Converts a Time instance to a Ruby DateTime instance, preserving UTC offset. # - # ==== Examples - # my_time = Time.now - # # => Mon Nov 12 23:04:21 -0500 2007 - # - # my_time.to_datetime - # # => Mon, 12 Nov 2007 23:04:21 -0500 - # - # your_time = Time.parse("1/13/2009 1:13:03 P.M.") - # # => Tue Jan 13 13:13:03 -0500 2009 + # my_time = Time.now # => Mon Nov 12 23:04:21 -0500 2007 + # my_time.to_datetime # => Mon, 12 Nov 2007 23:04:21 -0500 # - # your_time.to_datetime - # # => Tue, 13 Jan 2009 13:13:03 -0500 + # your_time = Time.parse("1/13/2009 1:13:03 P.M.") # => Tue Jan 13 13:13:03 -0500 2009 + # your_time.to_datetime # => Tue, 13 Jan 2009 13:13:03 -0500 def to_datetime ::DateTime.civil(year, month, day, hour, min, sec, Rational(utc_offset, 86400)) end activesupport/lib/active_support/core_ext/time/conversions.rb @@ -17,10 +17,9 @@ module ActiveSupport #:nodoc: # Sets a global default time zone, separate from the system time zone in ENV['TZ']. # Accepts either a Rails TimeZone object, a string that identifies a - # Rails TimeZone object (e.g., "Central Time (US & Canada)"), or a TZInfo::Timezone object + # Rails TimeZone object (e.g., "Central Time (US & Canada)"), or a TZInfo::Timezone object. # - # Any Time or DateTime object can use this default time zone, via #in_time_zone. - # Example: + # Any Time or DateTime object can use this default time zone, via <tt>in_time_zone</tt>. # # Time.zone = 'Hawaii' # => 'Hawaii' # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 activesupport/lib/active_support/core_ext/time/zones.rb @@ -1,11 +1,29 @@ -# Extensions to nil which allow for more helpful error messages for -# people who are new to rails. +# Extensions to +nil+ which allow for more helpful error messages for people who +# are new to Rails. # -# The aim is to ensure that when users pass nil to methods where that isn't -# appropriate, instead of NoMethodError and the name of some method used -# by the framework users will see a message explaining what type of object -# was expected. - +# Ruby raises NoMethodError if you invoke a method on an object that does not +# respond to it: +# +# $ ruby -e nil.destroy +# -e:1: undefined method `destroy' for nil:NilClass (NoMethodError) +# +# With these extensions, if the method belongs to the public interface of the +# classes in NilClass::WHINERS the error message suggests which could be the +# actual intended class: +# +# $ script/runner nil.destroy +# ... +# You might have expected an instance of ActiveRecord::Base. +# ... +# +# NilClass#id exists in Ruby 1.8 (though it is deprecated). Since +id+ is a fundamental +# method of Active Record models NilClass#id is redefined as well to raise a RuntimeError +# and warn the user. She probably wanted a model database identifier and the 4 +# returned by the original method could result in obscure bugs. +# +# The flag <tt>config.whiny_nils</tt> determines whether this feature is enabled. +# By default it is on in development and test modes, and it is off in production +# mode. class NilClass WHINERS = [::Array] WHINERS << ::ActiveRecord::Base if defined? ::ActiveRecord @@ -18,7 +36,7 @@ class NilClass methods.each { |method| @@method_class_map[method.to_sym] = class_name } end - # Raises a RuntimeError when you attempt to call id on nil or a nil object. + # Raises a RuntimeError when you attempt to call +id+ on +nil+. def id raise RuntimeError, "Called id for nil, which would mistakenly be 4 -- if you really wanted the id of nil, use object_id", caller end @@ -28,7 +46,7 @@ class NilClass raise_nil_warning_for @@method_class_map[method], method, caller end - # Raises a NoMethodError when you attempt to call a method on nil, or a nil object. + # Raises a NoMethodError when you attempt to call a method on +nil+. def raise_nil_warning_for(class_name = nil, selector = nil, with_caller = nil) message = "You have a nil object when you didn't expect it!" message << "\nYou might have expected an instance of #{class_name}." if class_name activesupport/lib/active_support/whiny_nil.rb 508eeb14f5eec45a05dc5db6de225443b9abae30 pratik pratik@5ecf4fe2-1ee6-0310-87b1-e25e094e27de http://github.com/NZKoz/koz-rails/commit/f4d52e424f4ee2585be68218b7390b69c22bb0b7 f4d52e424f4ee2585be68218b7390b69c22bb0b7 2008-04-04T20:52:58-07:00 2008-04-04T20:52:58-07:00 Improve documentation. git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9226 5ecf4fe2-1ee6-0310-87b1-e25e094e27de 22eadb1dc551f95e3150f803dc654eaa125544d9 pratik pratik@5ecf4fe2-1ee6-0310-87b1-e25e094e27de