From aa4af60aad5772458e8ba3bd08505781aeeb53a2 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 5 Apr 2008 03:52:58 +0000 Subject: Improve documentation. git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9226 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- .../lib/active_support/core_ext/array/access.rb | 6 ++-- .../active_support/core_ext/array/conversions.rb | 8 ++--- .../core_ext/array/extract_options.rb | 3 +- .../lib/active_support/core_ext/array/grouping.rb | 11 ++---- .../active_support/core_ext/array/random_access.rb | 2 +- activesupport/lib/active_support/core_ext/blank.rb | 5 ++- .../lib/active_support/core_ext/class/removal.rb | 33 +++++++++++++----- .../active_support/core_ext/date/calculations.rb | 4 +-- .../core_ext/date_time/conversions.rb | 2 +- .../active_support/core_ext/integer/even_odd.rb | 4 +-- .../active_support/core_ext/integer/inflections.rb | 2 -- .../core_ext/object/instance_variables.rb | 2 +- .../lib/active_support/core_ext/string/unicode.rb | 8 ++--- .../active_support/core_ext/time/conversions.rb | 39 +++++++--------------- .../lib/active_support/core_ext/time/zones.rb | 5 ++- activesupport/lib/active_support/whiny_nil.rb | 36 +++++++++++++++----- 16 files changed, 89 insertions(+), 81 deletions(-) (limited to 'activesupport/lib') diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb index fce319d3c6..21a8584bb9 100644 --- a/activesupport/lib/active_support/core_ext/array/access.rb +++ b/activesupport/lib/active_support/core_ext/array/access.rb @@ -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 ) diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb index e46d7c1884..34b1551abc 100644 --- a/activesupport/lib/active_support/core_ext/array/conversions.rb +++ b/activesupport/lib/active_support/core_ext/array/conversions.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 key 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 # # diff --git a/activesupport/lib/active_support/core_ext/array/extract_options.rb b/activesupport/lib/active_support/core_ext/array/extract_options.rb index 980d36400b..eb917576d7 100644 --- a/activesupport/lib/active_support/core_ext/array/extract_options.rb +++ b/activesupport/lib/active_support/core_ext/array/extract_options.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! diff --git a/activesupport/lib/active_support/core_ext/array/grouping.rb b/activesupport/lib/active_support/core_ext/array/grouping.rb index ed5ec72daf..767acc4e07 100644 --- a/activesupport/lib/active_support/core_ext/array/grouping.rb +++ b/activesupport/lib/active_support/core_ext/array/grouping.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 (nil by default) unless it is - # false. - # - # 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) diff --git a/activesupport/lib/active_support/core_ext/array/random_access.rb b/activesupport/lib/active_support/core_ext/array/random_access.rb index b7ee00742a..54d17cbf30 100644 --- a/activesupport/lib/active_support/core_ext/array/random_access.rb +++ b/activesupport/lib/active_support/core_ext/array/random_access.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 diff --git a/activesupport/lib/active_support/core_ext/blank.rb b/activesupport/lib/active_support/core_ext/blank.rb index f4def18ae9..dfe33162e8 100644 --- a/activesupport/lib/active_support/core_ext/blank.rb +++ b/activesupport/lib/active_support/core_ext/blank.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 diff --git a/activesupport/lib/active_support/core_ext/class/removal.rb b/activesupport/lib/active_support/core_ext/class/removal.rb index f768313abe..10660edb2c 100644 --- a/activesupport/lib/active_support/core_ext/class/removal.rb +++ b/activesupport/lib/active_support/core_ext/class/removal.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 diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb index d1a30c3f73..bb561f675f 100644 --- a/activesupport/lib/active_support/core_ext/date/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date/calculations.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 diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb index c86a527045..aa9caf1774 100644 --- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/date_time/conversions.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" diff --git a/activesupport/lib/active_support/core_ext/integer/even_odd.rb b/activesupport/lib/active_support/core_ext/integer/even_odd.rb index b53bcd066c..cfc6b4c6d6 100644 --- a/activesupport/lib/active_support/core_ext/integer/even_odd.rb +++ b/activesupport/lib/active_support/core_ext/integer/even_odd.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 diff --git a/activesupport/lib/active_support/core_ext/integer/inflections.rb b/activesupport/lib/active_support/core_ext/integer/inflections.rb index 252b2c5593..804702beb2 100644 --- a/activesupport/lib/active_support/core_ext/integer/inflections.rb +++ b/activesupport/lib/active_support/core_ext/integer/inflections.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" diff --git a/activesupport/lib/active_support/core_ext/object/instance_variables.rb b/activesupport/lib/active_support/core_ext/object/instance_variables.rb index f091acb969..ee1010b250 100644 --- a/activesupport/lib/active_support/core_ext/object/instance_variables.rb +++ b/activesupport/lib/active_support/core_ext/object/instance_variables.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 protected_instance_variables the ones returned are diff --git a/activesupport/lib/active_support/core_ext/string/unicode.rb b/activesupport/lib/active_support/core_ext/string/unicode.rb index 0e00b32194..0e9770af25 100644 --- a/activesupport/lib/active_support/core_ext/string/unicode.rb +++ b/activesupport/lib/active_support/core_ext/string/unicode.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 diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb index ab7b009663..edca5b8a98 100644 --- a/activesupport/lib/active_support/core_ext/time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/time/conversions.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 to_s. # - # ==== 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 diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb index 3096427904..d2b95698e5 100644 --- a/activesupport/lib/active_support/core_ext/time/zones.rb +++ b/activesupport/lib/active_support/core_ext/time/zones.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 in_time_zone. # # Time.zone = 'Hawaii' # => 'Hawaii' # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 diff --git a/activesupport/lib/active_support/whiny_nil.rb b/activesupport/lib/active_support/whiny_nil.rb index 983a14fd42..099619191c 100644 --- a/activesupport/lib/active_support/whiny_nil.rb +++ b/activesupport/lib/active_support/whiny_nil.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 config.whiny_nils 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 -- cgit v1.2.3