Enhanced RDoc for String#index (#5759)

2 files changed, 39 insertions, 30 deletions

diff --git a/doc/string/index.rdoc b/doc/string/index.rdoc
new file mode 100644
index 0000000000..ce09a37bdf
--- /dev/null
+++ b/doc/string/index.rdoc
@@ -0,0 +1,38 @@
+Returns the integer index of the first match for the given argument,
+or +nil+ if none found;
+the search of +self+ is forward, and begins at position +offset+ (in characters).
+
+With string argument +substring+,
+returns the index of the first matching substring in +self+:
+
+  'foo'.index('f')         # => 0
+  'foo'.index('o')         # => 1
+  'foo'.index('oo')        # => 1
+  'foo'.index('ooo')       # => nil
+  'тест'.index('с')        # => 2
+  'こんにちは'.index('ち')   # => 3
+
+With Regexp argument +regexp+, returns the index of the first match in +self+:
+
+  'foo'.index(/o./) # => 1
+  'foo'.index(/.o/) # => 0
+
+With positive integer +offset+, begins the search at position +offset+:
+
+  'foo'.index('o', 1)        # => 1
+  'foo'.index('o', 2)        # => 2
+  'foo'.index('o', 3)        # => nil
+  'тест'.index('с', 1)       # => 2
+  'こんにちは'.index('ち', 2)  # => 3
+
+With negative integer +offset+, selects the search position by counting backward
+from the end of +self+:
+
+  'foo'.index('o', -1)  # => 2
+  'foo'.index('o', -2)  # => 1
+  'foo'.index('o', -3)  # => 1
+  'foo'.index('o', -4)  # => nil
+  'foo'.index(/o./, -2) # => 1
+  'foo'.index(/.o/, -2) # => 1
+
+Related: String#rindex.
diff --git a/string.c b/string.c
index 4d5fea2962..2738ecbfcd 100644
--- a/string.c
+++ b/string.c
@@ -3850,37 +3850,8 @@ rb_strseq_index(VALUE str, VALUE sub, long offset, int in_byte)
  *    index(substring, offset = 0) -> integer or nil
  *    index(regexp, offset = 0) -> integer or nil
  *
- *  Returns the \Integer index of the first occurrence of the given +substring+,
- *  or +nil+ if none found:
- *
- *    'foo'.index('f') # => 0
- *    'foo'.index('o') # => 1
- *    'foo'.index('oo') # => 1
- *    'foo'.index('ooo') # => nil
- *
- *  Returns the \Integer index of the first match for the given \Regexp +regexp+,
- *  or +nil+ if none found:
- *
- *    'foo'.index(/f/) # => 0
- *    'foo'.index(/o/) # => 1
- *    'foo'.index(/oo/) # => 1
- *    'foo'.index(/ooo/) # => nil
- *
- *  \Integer argument +offset+, if given, specifies the position in the
- *  string to begin the search:
- *
- *    'foo'.index('o', 1) # => 1
- *    'foo'.index('o', 2) # => 2
- *    'foo'.index('o', 3) # => nil
- *
- *  If +offset+ is negative, counts backward from the end of +self+:
- *
- *    'foo'.index('o', -1) # => 2
- *    'foo'.index('o', -2) # => 1
- *    'foo'.index('o', -3) # => 1
- *    'foo'.index('o', -4) # => nil
+ *  :include: doc/string/index.rdoc
  *
- *  Related: String#rindex.
  */
 
 static VALUE