merge revision(s) ae6bd3b49ba252985b92416c24102ede3c0aac9b, 966458199d870b88b42898d4a063b487c1ef6b00, 966458199d870b88b42898d4a063b487c1ef6b00: [Backport #20951]

	[DOC] Tweak "Timezone Objects"

	- Make method descriptions plain pragraphs in each method.
	- Make "Argument" and "Returns" note-lists.

	[Bug #20951] [DOC] About UTC offset calculation after `utc_to_local`

	[Bug #20951] [DOC] About UTC offset calculation after `utc_to_local`

2 files changed, 29 insertions, 23 deletions

diff --git a/doc/_timezones.rdoc b/doc/_timezones.rdoc
index c5230ea67d..e355d699b4 100644
--- a/doc/_timezones.rdoc
+++ b/doc/_timezones.rdoc
@@ -64,43 +64,49 @@ The timezone methods are:
 
 - +local_to_utc+:
 
-  - Called when Time.new is invoked with +tz+
-    as the value of positional argument +zone+ or keyword argument +in:+.
-  - 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.
+  Called when Time.new is invoked with +tz+ as the value of positional
+  argument +zone+ or keyword argument +in:+.
+
+  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+:
 
-  - Called when Time.at or Time.now is invoked with +tz+
-    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 {Time-like object}[rdoc-ref:Time@Time-Like+Objects].
-  - Returns: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects] in the local timezone.
+  Called when Time.at or Time.now is invoked with +tz+ 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+.
+
+  The UTC offset will be calculated as the difference between the
+  original time and the returned object as an +Integer+.
+
+  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:
 
 - +abbr+:
 
-  - Called when Time#strftime is invoked with a format involving <tt>%Z</tt>.
-  - Argument: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects].
-  - Returns: a string abbreviation for the timezone name.
+  Called when Time#strftime is invoked with a format involving <tt>%Z</tt>.
+
+  Argument:: a {Time-like object}[rdoc-ref:Time@Time-Like+Objects].
+  Returns:: a string abbreviation for the timezone name.
 
 - +dst?+:
 
-  - Called when Time.at or Time.now is invoked with +tz+
-    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 {Time-like object}[rdoc-ref:Time@Time-Like+Objects].
-  - Returns: whether the time is daylight saving time.
+  Called when Time.at or Time.now is invoked with +tz+ 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 {Time-like object}[rdoc-ref:Time@Time-Like+Objects].
+  Returns:: whether the time is daylight saving time.
 
 - +name+:
 
-  - Called when <tt>Marshal.dump(t)</tt> is invoked
-  - Argument: none.
-  - Returns: the string name of the timezone.
+  Called when <tt>Marshal.dump(t)</tt> is invoked
+
+  Argument:: none.
+  Returns:: the string name of the timezone.
 
 ==== +Time+-Like Objects
 
diff --git a/version.h b/version.h
index cddd5935ff..9cc5f3bb4f 100644
--- a/version.h
+++ b/version.h
@@ -11,7 +11,7 @@
 # define RUBY_VERSION_MINOR RUBY_API_VERSION_MINOR
 #define RUBY_VERSION_TEENY 7
 #define RUBY_RELEASE_DATE RUBY_RELEASE_YEAR_STR"-"RUBY_RELEASE_MONTH_STR"-"RUBY_RELEASE_DAY_STR
-#define RUBY_PATCHLEVEL 123
+#define RUBY_PATCHLEVEL 124
 
 #include "ruby/version.h"
 #include "ruby/internal/abi.h"