[DOC] Update docs for rb_interned_str and related functions (#15897)

Related to [Bug #21842].

* rb_interned_str: document what decides whether the returned string is
  in US-ASCII or BINARY encoding.
* rb_interned_str_cstr: include the same description as rb_interned_str
  for the encoding. This one was still missing the update for US-ASCII
  and erroneously said the returned string was alwasy in BINARY encoding
* rb_str_to_interned_str: document how the encoding of the result is
  defined.

Co-authored-by: Herwin <herwinw@users.noreply.github.com>

1 files changed, 8 insertions, 6 deletions

diff --git a/include/ruby/internal/intern/string.h b/include/ruby/internal/intern/string.h
index 2ec08fc81f..8bd1ffcfb4 100644
--- a/include/ruby/internal/intern/string.h
+++ b/include/ruby/internal/intern/string.h
@@ -412,8 +412,8 @@ VALUE rb_utf8_str_new_static(const char *ptr, long len);
 
 /**
  * Identical to rb_interned_str(),  except it takes a Ruby's  string instead of
- * C's.  It can also be seen  as a routine identical to rb_str_new_shared(),
- * except it returns an infamous "f"string.
+ * C's and preserves its encoding.  It can also be seen  as a routine identical
+ * to rb_str_new_shared(), except it returns an infamous "f"string.
  *
  * @param[in]  str  An object of ::RString.
  * @return     An instance  of ::rb_cString, either cached  or allocated, which
@@ -444,8 +444,9 @@ VALUE rb_str_to_interned_str(VALUE str);
  *                           terminating NUL character.
  * @exception  rb_eArgError  `len` is negative.
  * @return     A  found or  created instance  of ::rb_cString,  of `len`  bytes
- *             length,  of US-ASCII  or "binary"  encoding, whose  contents are
- *             identical to that of `ptr`.
+ *             length,  whose  contents  are  identical  to that of `ptr`.  Its
+ *             encoding  will  be US-ASCII if all bytes are lower ASCII, BINARY
+ *             otherwise.
  * @pre        At  least  `len` bytes  of  continuous  memory region  shall  be
  *             accessible via `ptr`.
  */
@@ -461,8 +462,9 @@ RBIMPL_ATTR_NONNULL(())
  *
  * @param[in]  ptr             A C string.
  * @exception  rb_eNoMemError  Failed to allocate memory.
- * @return     An  instance  of  ::rb_cString,   of  "binary"  encoding,  whose
- *             contents are verbatim copy of `ptr`.
+ * @return     An  instance  of  ::rb_cString, whose contents are verbatim copy
+ *             of `ptr`. Its encoding  will  be US-ASCII if all bytes are lower
+ *             ASCII, BINARY otherwise.
  * @pre        `ptr` must not be a null pointer.
  */
 VALUE rb_interned_str_cstr(const char *ptr);