[DOC] Mention Time-like objects

1 files changed, 32 insertions, 6 deletions

diff --git a/doc/_timezones.rdoc b/doc/_timezones.rdoc
index 509d4e59b7..61bc7e5a81 100644
--- a/doc/_timezones.rdoc
+++ b/doc/_timezones.rdoc
@@ -66,8 +66,8 @@ The timezone methods are:
 
   - Called when Time.new is invoked with +tz+
     as the value of positional argument +zone+ or keyword argument +in:+.
-  - Argument: a <tt>Time::tm</tt> object.
-  - Returns: a \Time-like object in the UTC timezone.
+  - Argument: a {Time-like object}[rdoc-ref:Time@Time-like+Objects].
+  - Returns: a {Time-like object}[rdoc-ref:Time@Time-like+Objects] in the UTC timezone.
 
 - +utc_to_local+:
 
@@ -75,8 +75,8 @@ The timezone methods are:
     as the value for keyword argument +in:+,
     and when Time#getlocal or Time#localtime is called with +tz+
     as the value for positional argument +zone+.
-  - Argument: a <tt>Time::tm</tt> object.
-  - Returns: a \Time-like object in the local timezone.
+  - Argument: a {Time-like object}[rdoc-ref:Time@Time-like+Objects].
+  - Returns: a {Time-like object}[rdoc-ref:Time@Time-like+Objects] in the local timezone.
 
 A custom timezone class may have these instance methods,
 which will be called if defined:
@@ -84,7 +84,7 @@ which will be called if defined:
 - +abbr+:
 
   - Called when Time#strftime is invoked with a format involving <tt>%Z</tt>.
-  - Argument: a <tt>Time::tm</tt> object.
+  - Argument: a {Time-like object}[rdoc-ref:Time@Time-like+Objects].
   - Returns: a string abbreviation for the timezone name.
 
 - +dst?+:
@@ -93,7 +93,7 @@ which will be called if defined:
     as the value for keyword argument +in:+,
     and when Time#getlocal or Time#localtime is called with +tz+
     as the value for positional argument +zone+.
-  - Argument: a <tt>Time::tm</tt> object.
+  - Argument: a {Time-like object}[rdoc-ref:Time@Time-like+Objects].
   - Returns: whether the time is daylight saving time.
 
 - +name+:
@@ -102,6 +102,32 @@ which will be called if defined:
   - Argument: none.
   - Returns: the string name of the timezone.
 
+==== +Time+-like Objects
+
+A +Time+-like object means a container object to interface with
+timezone libraries for timezone conversion.
+
+An argument object to the timezone conversion methods above will have
+attributes similar to Time, except for that timezone related attributes
+are meaningless.
+
+The objects returned by +local_to_utc+ and +utc_to_local+ methods of the
+timezone object may be of the same class as their arguments, arbitrary
+object classes, or Integer class.  The others than +Integer+ just must
+have the following attributes:
+
+- +year+
+- +mon+
+- +mday+
+- +hour+
+- +min+
+- +sec+
+- +isdst+
+- +to_i+
+
+In the case an +Integer+ is returned, its components, decomposed in UTC,
+are interpreted as times in the specified timezone.
+
 === Timezone Names
 
 If the class (the receiver of class methods, or the class of the receiver