[pull] master from ruby:master

array.c

@@ -2098,13 +2098,13 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
  * With a block given, calls the block with successive elements of the array;
  * returns the first element for which the block returns a truthy value:
  *
- *   (0..9).find {|element| element > 2}                # => 3
+ *   [1, 3, 5].find {|element| element > 2}                # => 3
  *
  * If no such element is found, calls +if_none_proc+ and returns its return value.
  *
- *   (0..9).find(proc {false}) {|element| element > 12} # => false
- *   {foo: 0, bar: 1, baz: 2}.find {|key, value| key.start_with?('b') }            # => [:bar, 1]
- *   {foo: 0, bar: 1, baz: 2}.find(proc {[]}) {|key, value| key.start_with?('c') } # => []
+ *   [1, 3, 5].find(proc {false}) {|element| element > 12} # => false
+ *   [[:foo, 0], [:bar, 1], [:baz, 2]].find {|key, value| key.start_with?('b') }            # => [:bar, 1]
+ *   [[:foo, 0], [:bar, 1], [:baz, 2]].find(proc {[]}) {|key, value| key.start_with?('c') } # => []
  *
  * With no block given, returns an Enumerator.
  *

include/ruby/internal/ctype.h

@@ -498,8 +498,8 @@ RBIMPL_ATTR_ARTIFICIAL()
  * Our own locale-insensitive version of `tolower(3)`.
  *
  * @param[in]  c          Byte in question to convert.
- * @retval     c          The  byte is  not listed  in  IEEE 1003.1  section
- *                        7.3.1.1 "upper".
+ * @retval     c          The byte is not listed  in IEEE 1003.1 section 7.3.1.1
+ *                        "upper".
  * @retval     otherwise  Byte converted  using the map defined  in IEEE 1003.1
  *                        section 7.3.1 "tolower".
  * @note       Not only  does this function  works under the POSIX  Locale, but

include/ruby/internal/symbol.h

@@ -101,12 +101,11 @@ ID rb_intern(const char *name);
 ID rb_intern2(const char *name, long len);
 
 /**
- * Identical to  rb_intern(), except  it takes an instance of ::rb_cString.
+ * Identical to rb_intern(), except it takes a `T_STRING` object.
  *
  * @param[in]  str               The name of the id.
- * @pre        `str` must either be an instance of ::rb_cSymbol, or an instance
- *             of ::rb_cString, or responds to `#to_str` method.
- * @exception  rb_eTypeError     Can't convert `str` into ::rb_cString.
+ * @pre        `rb_type(str)` must be `T_STRING`.
+ * @exception  rb_eEncodingError `str` contains invalid character(s).
  * @exception  rb_eRuntimeError  Too many symbols.
  * @return     A (possibly new) id whose value is the given str.
  * @note       These   days  Ruby   internally   has  two   kinds  of   symbols
@@ -166,29 +165,34 @@ RBIMPL_ATTR_NONNULL(())
  *                 of ::rb_cSymbol, or an instance of ::rb_cString, or responds
  *                 to `#to_str` method.
  * @exception      rb_eTypeError      Can't convert `*namep` into ::rb_cString.
- * @exception      rb_eEncodingError  Given string is non-ASCII.
+ * @exception      rb_eEncodingError  Given string contains invalid character(s).
  * @retval         0                  No such id ever existed in the history.
  * @retval         otherwise          The id that represents the given name.
  * @post           The object  that `*namep`  points to  is a  converted result
  *                 object, which  is always an instance  of either ::rb_cSymbol
  *                 or ::rb_cString.
+ * @see            rb_str_to_str
  * @see            https://bugs.ruby-lang.org/issues/5072
- *
- * @internal
- *
- * @shyouhei doesn't know why this has to raise rb_eEncodingError.
  */
 ID rb_check_id(volatile VALUE *namep);
 
 /**
- * @copydoc rb_intern_str()
+ * Identical to rb_intern_str(), except it tries to convert the parameter object
+ * to an instance of ::rb_cString or its subclasses.
  *
- * @internal
- *
- * :FIXME:  Can anyone  tell us  what is  the difference  between this  one and
- * rb_intern_str()?  As far as @shyouhei reads the implementation it seems what
- * rb_to_id() does is just waste some CPU time,  then call rb_intern_str().
- * He hopes he is wrong.
+ * @param[in]  str               The name of the id.
+ * @pre        `str` must either be an  instance of ::rb_cSymbol, or an instance
+ *             of ::rb_cString, or responds to `#to_str` method.
+ * @exception  rb_eTypeError     Can't convert `str` into ::rb_cString.
+ * @exception  rb_eEncodingError Given string contains invalid character(s).
+ * @exception  rb_eRuntimeError  Too many symbols.
+ * @return     A (possibly new) id whose value is the given str.
+ * @note       These   days  Ruby   internally   has  two   kinds  of   symbols
+ *             (static/dynamic).   Symbols created  using  this function  would
+ *             become static ones;  i.e. would never be  garbage collected.  It
+ *             is up  to you to avoid  memory leaks.  Think twice  before using
+ *             it.
+ * @see        rb_str_to_str
  */
 ID rb_to_id(VALUE str);
 
@@ -245,17 +249,14 @@ RBIMPL_ATTR_NONNULL(())
  *                 of ::rb_cSymbol, or an instance of ::rb_cString, or responds
  *                 to `#to_str` method.
  * @exception      rb_eTypeError      Can't convert `*namep` into ::rb_cString.
- * @exception      rb_eEncodingError  Given string is non-ASCII.
+ * @exception      rb_eEncodingError  Given string contains invalid character(s).
  * @retval         RUBY_Qnil          No such id ever existed in the history.
  * @retval         otherwise          The id that represents the given name.
  * @post           The object  that `*namep`  points to  is a  converted result
  *                 object, which  is always an instance  of either ::rb_cSymbol
  *                 or ::rb_cString.
  * @see            https://bugs.ruby-lang.org/issues/5072
- *
- * @internal
- *
- * @shyouhei doesn't know why this has to raise rb_eEncodingError.
+ * @see            rb_str_to_str
  */
 VALUE rb_check_symbol(volatile VALUE *namep);
 RBIMPL_SYMBOL_EXPORT_END()