From 468ce1488d26ffc92c940324794dc9257f72b5d2 Mon Sep 17 00:00:00 2001
From: Nobuyoshi Nakada <nobu@ruby-lang.org>
Date: Sun, 15 Jan 2023 22:19:20 +0900
Subject: [PATCH] [DOC] Use RDoc inclusions in transcode.c

---
 doc/string/encode.rdoc | 40 ++++++++++++++++++++++++++++++++
 doc/transcode.rdoc     | 52 ------------------------------------------
 transcode.c            |  9 ++++++++
 3 files changed, 49 insertions(+), 52 deletions(-)
 create mode 100644 doc/string/encode.rdoc
 delete mode 100644 doc/transcode.rdoc

diff --git a/doc/string/encode.rdoc b/doc/string/encode.rdoc
new file mode 100644
index 0000000000..2872887ef1
--- /dev/null
+++ b/doc/string/encode.rdoc
@@ -0,0 +1,40 @@
+Returns a copy of +self+ transcoded as determined by +dst_encoding+.
+By default, raises an exception if +self+
+contains an invalid byte or a character not defined in +dst_encoding+;
+that behavior may be modified by encoding options; see below.
+
+With no arguments:
+
+- Uses the same encoding if <tt>Encoding.default_internal</tt> is +nil+
+  (the default):
+
+    Encoding.default_internal # => nil
+    s = "Ruby\x99".force_encoding('Windows-1252')
+    s.encoding                # => #<Encoding:Windows-1252>
+    s.bytes                   # => [82, 117, 98, 121, 153]
+    t = s.encode              # => "Ruby\x99"
+    t.encoding                # => #<Encoding:Windows-1252>
+    t.bytes                   # => [82, 117, 98, 121, 226, 132, 162]
+
+- Otherwise, uses the encoding <tt>Encoding.default_internal</tt>:
+
+    Encoding.default_internal = 'UTF-8'
+    t = s.encode              # => "Ruby™"
+    t.encoding                # => #<Encoding:UTF-8>
+
+With only argument +dst_encoding+ given, uses that encoding:
+
+  s = "Ruby\x99".force_encoding('Windows-1252')
+  s.encoding            # => #<Encoding:Windows-1252>
+  t = s.encode('UTF-8') # => "Ruby™"
+  t.encoding            # => #<Encoding:UTF-8>
+
+With arguments +dst_encoding+ and +src_encoding+ given,
+interprets +self+ using +src_encoding+, encodes the new string using +dst_encoding+:
+
+  s = "Ruby\x99"
+  t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™"
+  t.encoding                            # => #<Encoding:UTF-8>
+
+Optional keyword arguments +enc_opts+ specify encoding options;
+see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
diff --git a/doc/transcode.rdoc b/doc/transcode.rdoc
deleted file mode 100644
index 4f15dff94a..0000000000
--- a/doc/transcode.rdoc
+++ /dev/null
@@ -1,52 +0,0 @@
-# :markup: ruby
-
-class String
-  # call-seq:
-  #   encode(dst_encoding = Encoding.default_internal, **enc_opts) -> string
-  #   encode(dst_encoding, src_encoding, **enc_opts)   -> string
-  #
-  # Returns a copy of +self+ transcoded as determined by +dst_encoding+.
-  # By default, raises an exception if +self+
-  # contains an invalid byte or a character not defined in +dst_encoding+;
-  # that behavior may be modified by encoding options; see below.
-  #
-  # With no arguments:
-  #
-  # - Uses the same encoding if <tt>Encoding.default_internal</tt> is +nil+
-  #   (the default):
-  #
-  #     Encoding.default_internal # => nil
-  #     s = "Ruby\x99".force_encoding('Windows-1252')
-  #     s.encoding                # => #<Encoding:Windows-1252>
-  #     s.bytes                   # => [82, 117, 98, 121, 153]
-  #     t = s.encode              # => "Ruby\x99"
-  #     t.encoding                # => #<Encoding:Windows-1252>
-  #     t.bytes                   # => [82, 117, 98, 121, 226, 132, 162]
-  #
-  # - Otherwise, uses the encoding <tt>Encoding.default_internal</tt>:
-  #
-  #     Encoding.default_internal = 'UTF-8'
-  #     t = s.encode              # => "Ruby™"
-  #     t.encoding                # => #<Encoding:UTF-8>
-  #
-  # With only argument +dst_encoding+ given, uses that encoding:
-  #
-  #   s = "Ruby\x99".force_encoding('Windows-1252')
-  #   s.encoding            # => #<Encoding:Windows-1252>
-  #   t = s.encode('UTF-8') # => "Ruby™"
-  #   t.encoding            # => #<Encoding:UTF-8>
-  #
-  # With arguments +dst_encoding+ and +src_encoding+ given,
-  # interprets +self+ using +src_encoding+, encodes the new string using +dst_encoding+:
-  #
-  #   s = "Ruby\x99"
-  #   t = s.encode('UTF-8', 'Windows-1252') # => "Ruby™"
-  #   t.encoding                            # => #<Encoding:UTF-8>
-  #
-  # Optional keyword arguments +enc_opts+ specify encoding options;
-  # see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
-  def encode(dst_encoding = Encoding.default_internal, **enc_opts)
-    # Pseudo code
-    Primitive.str_encode(...)
-  end
-end
diff --git a/transcode.c b/transcode.c
index f1d871e292..2cceecfebc 100644
--- a/transcode.c
+++ b/transcode.c
@@ -2872,6 +2872,15 @@ str_encode_bang(int argc, VALUE *argv, VALUE str)
 
 static VALUE encoded_dup(VALUE newstr, VALUE str, int encidx);
 
+/*
+ *  call-seq:
+ *    encode(dst_encoding = Encoding.default_internal, **enc_opts) -> string
+ *    encode(dst_encoding, src_encoding, **enc_opts)   -> string
+ *
+ *  :include: doc/string/encode.rdoc
+ *
+ */
+
 static VALUE
 str_encode(int argc, VALUE *argv, VALUE str)
 {