[DOC] Enhanced RDoc for String (#5707)

Treated:

    #chomp
    #chomp!
    #chop
    #chop!

2 files changed, 45 insertions, 0 deletions

diff --git a/doc/string/chomp.rdoc b/doc/string/chomp.rdoc
new file mode 100644
index 0000000000..b6fb9ff38c
--- /dev/null
+++ b/doc/string/chomp.rdoc
@@ -0,0 +1,29 @@
+Returns a new string copied from +self+, with trailing characters possibly removed:
+
+When +line_sep+ is <tt>"\n"</tt>, removes the last one or two characters
+if they are <tt>"\r"</tt>, <tt>"\n"</tt>, or <tt>"\r\n"</tt>
+(but not <tt>"\n\r"</tt>):
+
+  $/                    # => "\n"
+  "abc\r".chomp         # => "abc"
+  "abc\n".chomp         # => "abc"
+  "abc\r\n".chomp       # => "abc"
+  "abc\n\r".chomp       # => "abc\n"
+  "тест\r\n".chomp      # => "тест"
+  "こんにちは\r\n".chomp  # => "こんにちは"
+
+When +line_sep+ is <tt>''</tt> (an empty string),
+removes multiple trailing occurrences of <tt>"\n"</tt> or <tt>"\r\n"</tt>
+(but not <tt>"\r"</tt> or <tt>"\n\r"</tt>):
+
+  "abc\n\n\n".chomp('')           # => "abc"
+  "abc\r\n\r\n\r\n".chomp('')     # => "abc"
+  "abc\n\n\r\n\r\n\n\n".chomp('') # => "abc"
+  "abc\n\r\n\r\n\r".chomp('')     # => "abc\n\r\n\r\n\r"
+  "abc\r\r\r".chomp('')           # => "abc\r\r\r"
+
+When +line_sep+ is neither <tt>"\n"</tt> nor <tt>''</tt>,
+removes a single trailing line separator if there is one:
+
+  'abcd'.chomp('d')  # => "abc"
+  'abcdd'.chomp('d') # => "abcd"
diff --git a/doc/string/chop.rdoc b/doc/string/chop.rdoc
new file mode 100644
index 0000000000..8ef82f8a49
--- /dev/null
+++ b/doc/string/chop.rdoc
@@ -0,0 +1,16 @@
+Returns a new string copied from +self+, with trailing characters possibly removed.
+
+Removes <tt>"\r\n"</tt> if those are the last two characters.
+
+  "abc\r\n".chop      # => "abc"
+  "тест\r\n".chop     # => "тест"
+  "こんにちは\r\n".chop # => "こんにちは"
+
+Otherwise removes the last character if it exists.
+
+  'abcd'.chop     # => "abc"
+  'тест'.chop     # => "тес"
+  'こんにちは'.chop # => "こんにち"
+  ''.chop         # => ""
+
+If you only need to remove the newline separator at the end of the string, String#chomp is a better alternative.