From f2d2a757d1b3a11b68e60ee08162e58f59837bb3 Mon Sep 17 00:00:00 2001 From: Nobuyoshi Nakada Date: Thu, 18 Dec 2025 10:14:40 +0900 Subject: [PATCH 1/3] [DOC] Re-fill the paragraph --- include/ruby/internal/ctype.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/ruby/internal/ctype.h b/include/ruby/internal/ctype.h index 93e92801fcc5a3..8b24026311e6a5 100644 --- a/include/ruby/internal/ctype.h +++ b/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 From b816f7bac5f2dfb10c7a468c14cfcdedaab2f7ae Mon Sep 17 00:00:00 2001 From: Nobuyoshi Nakada Date: Thu, 18 Dec 2025 11:27:05 +0900 Subject: [PATCH 2/3] [DOC] Fix documents of `rb_intern_str` and so on * `rb_intern_str`: the argument must be `T_STRING`, no conversion. * `rb_intern_str`, `rb_check_id`, `rb_to_id`, `rb_check_symbol`: raise `EncodingError` unless the "name" argument is a valid string in its encoding. --- include/ruby/internal/symbol.h | 43 +++++++++++++++++----------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/include/ruby/internal/symbol.h b/include/ruby/internal/symbol.h index 858c5e290f6463..8bfd686fbe6487 100644 --- a/include/ruby/internal/symbol.h +++ b/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() From 769c6a1c54e68d0100054e51fc25e1a6355645c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Barri=C3=A9?= Date: Mon, 15 Dec 2025 14:47:54 +0100 Subject: [PATCH 3/3] [DOC] Use Arrays in examples for Array#find --- array.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/array.c b/array.c index b9d91d0a9b296f..27b84249bf44fe 100644 --- a/array.c +++ b/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. *