From 64092de25727c1943807bf5345107d90428135a0 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Fri, 2 May 2008 14:45:23 +0100 Subject: Improve documentation coverage and markup Signed-off-by: Pratik Naik --- .../active_support/core_ext/array/conversions.rb | 51 ++++++++++++++++++---- .../core_ext/class/attribute_accessors.rb | 8 +++- .../active_support/core_ext/date/calculations.rb | 2 +- .../core_ext/date_time/calculations.rb | 6 ++- .../lib/active_support/core_ext/enumerable.rb | 21 ++++----- .../active_support/core_ext/hash/reverse_merge.rb | 2 +- .../core_ext/module/attribute_accessors.rb | 12 ++++- .../active_support/core_ext/module/delegation.rb | 8 ++-- .../active_support/core_ext/range/include_range.rb | 8 ++++ .../lib/active_support/core_ext/range/overlaps.rb | 3 ++ .../active_support/core_ext/time/calculations.rb | 10 +++-- 11 files changed, 100 insertions(+), 31 deletions(-) (limited to 'activesupport/lib/active_support/core_ext') diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb index 34b1551abc..a9882828ca 100644 --- a/activesupport/lib/active_support/core_ext/array/conversions.rb +++ b/activesupport/lib/active_support/core_ext/array/conversions.rb @@ -67,17 +67,35 @@ module ActiveSupport #:nodoc: end end - # Returns a string that represents this array in XML by sending - # to_xml to each element. + # Returns a string that represents this array in XML by sending +to_xml+ + # to each element. Active Record collections delegate their representation + # in XML to this method. # - # All elements are expected to respond to to_xml, if any of - # them does not an exception is raised. + # All elements are expected to respond to +to_xml+, if any of them does + # not an exception is raised. # # The root node reflects the class name of the first element in plural - # if all elements belong to the same type and that's not Hash. - # Otherwise the root element is "records". + # if all elements belong to the same type and that's not Hash: # - # Root children have as node name the one of the root singularized. + # customer.projects.to_xml + # + # + # + # + # 20000.0 + # 1567 + # 2008-04-09 + # ... + # + # + # 57230.0 + # 1567 + # 2008-04-15 + # ... + # + # + # + # Otherwise the root element is "records": # # [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml # @@ -92,9 +110,26 @@ module ActiveSupport #:nodoc: # # # + # If the collection is empty the root element is "nil-classes" by default: + # + # [].to_xml + # + # + # + # + # To ensure a meaningful root element use the :root option: + # + # customer_with_no_projects.projects.to_xml(:root => "projects") + # + # + # + # + # By default root children have as node name the one of the root + # singularized. You can change it with the :children option. + # # The +options+ hash is passed downwards: # - # [Message.find(:first)].to_xml(:skip_types => true) + # Message.all.to_xml(:skip_types => true) # # # diff --git a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb index eee61d48c4..186ca69c05 100644 --- a/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb +++ b/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb @@ -1,6 +1,12 @@ # Extends the class object with class and instance accessors for class attributes, # just like the native attr* accessors for instance attributes. -class Class # :nodoc: +# +# class Person +# cattr_accessor :hair_colors +# end +# +# Person.hair_colors = [:brown, :black, :blonde, :red] +class Class def cattr_reader(*syms) syms.flatten.each do |sym| next if sym.is_a?(Hash) diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb index bb561f675f..183471706b 100644 --- a/activesupport/lib/active_support/core_ext/date/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date/calculations.rb @@ -70,7 +70,7 @@ module ActiveSupport #:nodoc: end # Provides precise Date calculations for years, months, and days. The +options+ parameter takes a hash with - # any of these keys: :years, :months, :weeks, :days. + # any of these keys: :years, :months, :weeks, :days. def advance(options) d = self d = d >> options.delete(:years) * 12 if options[:years] diff --git a/activesupport/lib/active_support/core_ext/date_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_time/calculations.rb index fa444f71b1..155c961a91 100644 --- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb @@ -42,8 +42,10 @@ module ActiveSupport #:nodoc: ) end - # Uses Date to provide precise Time calculations for years, months, and days. The +options+ parameter takes a hash with - # any of these keys: :years, :months, :weeks, :days, :hours, :minutes, :seconds. + # Uses Date to provide precise Time calculations for years, months, and days. + # The +options+ parameter takes a hash with any of these keys: :years, + # :months, :weeks, :days, :hours, + # :minutes, :seconds. def advance(options) d = to_date.advance(options) datetime_advanced_by_date = change(:year => d.year, :month => d.month, :day => d.day) diff --git a/activesupport/lib/active_support/core_ext/enumerable.rb b/activesupport/lib/active_support/core_ext/enumerable.rb index 8f111e29fc..f1469aa0e3 100644 --- a/activesupport/lib/active_support/core_ext/enumerable.rb +++ b/activesupport/lib/active_support/core_ext/enumerable.rb @@ -8,7 +8,7 @@ module Enumerable # Example: # # latest_transcripts.group_by(&:day).each do |day, transcripts| - # p "#{day} -> #{transcripts.map(&:class) * ', '}" + # p "#{day} -> #{transcripts.map(&:class).join(', ')}" # end # "2006-03-01 -> Transcript" # "2006-02-28 -> Transcript" @@ -26,21 +26,22 @@ module Enumerable # Calculates a sum from the elements. Examples: # - # payments.sum { |p| p.price * p.tax_rate } - # payments.sum(&:price) + # payments.sum { |p| p.price * p.tax_rate } + # payments.sum(&:price) # - # This is instead of + # The latter is a shortcut for: # - # payments.inject { |sum, p| sum + p.price } + # payments.inject { |sum, p| sum + p.price } # - # Also calculates sums without the use of a block: + # It can also calculate the sum without the use of a block. # - # [5, 15, 10].sum # => 30 + # [5, 15, 10].sum # => 30 + # ["foo", "bar"].sum # => "foobar" + # [[1, 2], [3, 1, 5]].sum => [1, 2, 3, 1, 5] # - # The default identity (sum of an empty list) is zero. - # However, you can override this default: + # The default sum of an empty list is zero. You can override this default: # - # [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) + # [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) # def sum(identity = 0, &block) return identity unless size > 0 diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb index 0ec0538024..7af10846e7 100644 --- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb +++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb @@ -8,7 +8,7 @@ module ActiveSupport #:nodoc: # options.reverse_merge! :size => 25, :velocity => 10 # end # - # The default :size and :velocity is only set if the +options+ passed in doesn't already have those keys set. + # The default :size and :velocity is only set if the +options+ passed in doesn't already have those keys set. module ReverseMerge # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second. def reverse_merge(other_hash) diff --git a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb index 58ff363244..51e1c9af90 100644 --- a/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb +++ b/activesupport/lib/active_support/core_ext/module/attribute_accessors.rb @@ -1,6 +1,16 @@ # Extends the module object with module and instance accessors for class attributes, # just like the native attr* accessors for instance attributes. -class Module # :nodoc: +# +# module AppConfiguration +# mattr_accessor :google_api_key +# self.google_api_key = "123456789" +# +# mattr_accessor :paypal_url +# self.paypal_url = "www.sandbox.paypal.com" +# end +# +# AppConfiguration.google_api_key = "overriding the api key!" +class Module def mattr_reader(*syms) syms.each do |sym| next if sym.is_a?(Hash) diff --git a/activesupport/lib/active_support/core_ext/module/delegation.rb b/activesupport/lib/active_support/core_ext/module/delegation.rb index f6647eaed3..e0b5f3e379 100644 --- a/activesupport/lib/active_support/core_ext/module/delegation.rb +++ b/activesupport/lib/active_support/core_ext/module/delegation.rb @@ -1,8 +1,8 @@ class Module # Provides a delegate class method to easily expose contained objects' methods # as your own. Pass one or more methods (specified as symbols or strings) - # and the name of the target object as the final :to option (also a symbol - # or string). At least one method and the :to option are required. + # and the name of the target object as the final :to option (also a symbol + # or string). At least one method and the :to option are required. # # Delegation is particularly useful with Active Record associations: # @@ -20,6 +20,7 @@ class Module # Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for # # # Multiple delegates to the same target are allowed: + # # class Foo < ActiveRecord::Base # belongs_to :greeter # delegate :hello, :goodbye, :to => :greeter @@ -28,7 +29,8 @@ class Module # Foo.new.goodbye # => "goodbye" # # Methods can be delegated to instance variables, class variables, or constants - # by providing the variable as a symbol: + # by providing them as a symbols: + # # class Foo # CONSTANT_ARRAY = [0,1,2,3] # @@class_array = [4,5,6,7] diff --git a/activesupport/lib/active_support/core_ext/range/include_range.rb b/activesupport/lib/active_support/core_ext/range/include_range.rb index cd53cf154a..9a7d235695 100644 --- a/activesupport/lib/active_support/core_ext/range/include_range.rb +++ b/activesupport/lib/active_support/core_ext/range/include_range.rb @@ -7,6 +7,14 @@ module ActiveSupport #:nodoc: base.alias_method_chain :include?, :range end + # Extends the default Range#include? to support range comparisons. + # (1..5).include?(1..5) # => true + # (1..5).include?(2..3) # => true + # (1..5).include?(2..6) # => false + # + # The native Range#include? behavior is untouched. + # ("a".."f").include?("c") # => true + # (5..9).include?(11) # => false def include_with_range?(value) if value.is_a?(::Range) operator = exclude_end? ? :< : :<= diff --git a/activesupport/lib/active_support/core_ext/range/overlaps.rb b/activesupport/lib/active_support/core_ext/range/overlaps.rb index 80ed1bba9d..43c69453e7 100644 --- a/activesupport/lib/active_support/core_ext/range/overlaps.rb +++ b/activesupport/lib/active_support/core_ext/range/overlaps.rb @@ -3,6 +3,9 @@ module ActiveSupport #:nodoc: module Range #:nodoc: # Check if Ranges overlap. module Overlaps + # Compare two ranges and see if they overlap eachother + # (1..5).overlaps?(4..6) # => true + # (1..5).overlaps?(7..9) # => false def overlaps?(other) include?(other.first) || other.include?(first) end diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb index ffbdf37789..2cce782676 100644 --- a/activesupport/lib/active_support/core_ext/time/calculations.rb +++ b/activesupport/lib/active_support/core_ext/time/calculations.rb @@ -46,12 +46,12 @@ module ActiveSupport #:nodoc: ::DateTime.civil(year, month, day, hour, min, sec, offset) end - # wraps class method time_with_datetime_fallback with utc_or_local == :utc + # Wraps class method +time_with_datetime_fallback+ with +utc_or_local+ set to :utc. def utc_time(*args) time_with_datetime_fallback(:utc, *args) end - # wraps class method time_with_datetime_fallback with utc_or_local == :local + # Wraps class method +time_with_datetime_fallback+ with +utc_or_local+ set to :local. def local_time(*args) time_with_datetime_fallback(:local, *args) end @@ -78,8 +78,10 @@ module ActiveSupport #:nodoc: ) end - # Uses Date to provide precise Time calculations for years, months, and days. The +options+ parameter takes a hash with - # any of these keys: :years, :months, :weeks, :days, :hours, :minutes, :seconds. + # Uses Date to provide precise Time calculations for years, months, and days. + # The +options+ parameter takes a hash with any of these keys: :years, + # :months, :weeks, :days, :hours, + # :minutes, :seconds. def advance(options) d = to_date.advance(options) time_advanced_by_date = change(:year => d.year, :month => d.month, :day => d.day) -- cgit v1.2.3