Add docs for Time#find_zone

Also improves docs for `Time#find_zone!`

[ci skip]

1 files changed, 16 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index 64c3b7201b..7f295a88ed 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -51,7 +51,16 @@ class Time
       end
     end
 
-    # Returns a TimeZone instance or nil, or raises an ArgumentError for invalid timezones.
+    # Returns a TimeZone instance matching the time zone provided.
+    # Accepts the time zone in any format supported by <tt>Time.zone=</tt>.
+    # Raises an ArgumentError for invalid time zones.
+    #
+    #   Time.find_zone! "America/New_York" #=> #<ActiveSupport::TimeZone @name="America/New_York" ...>
+    #   Time.find_zone! "EST"              #=> #<ActiveSupport::TimeZone @name="EST" ...>
+    #   Time.find_zone! -5.hours           #=> #<ActiveSupport::TimeZone @name="Bogota" ...>
+    #   Time.find_zone! nil                #=> nil
+    #   Time.find_zone! false              #=> false
+    #   Time.find_zone! "NOT-A-TIMEZONE"   #=> ArgumentError: Invalid Timezone: NOT-A-TIMEZONE
     def find_zone!(time_zone)
       if !time_zone || time_zone.is_a?(ActiveSupport::TimeZone)
         time_zone
@@ -72,6 +81,12 @@ class Time
       raise ArgumentError, "Invalid Timezone: #{time_zone}"
     end
 
+    # Returns a TimeZone instance matching the time zone provided.
+    # Accepts the time zone in any format supported by <tt>Time.zone=</tt>.
+    # Returns +nil+ for invalid time zones.
+    #
+    #   Time.find_zone "America/New_York" #=> #<ActiveSupport::TimeZone @name="America/New_York" ...>
+    #   Time.find_zone "NOT-A-TIMEZONE"   #=> nil
     def find_zone(time_zone)
       find_zone!(time_zone) rescue nil
     end