1 files changed, 5 insertions, 2 deletions
diff --git a/string.c b/string.c
index 3168b72343..a922c9269a 100644
--- a/string.c
+++ b/string.c
@@ -4965,13 +4965,16 @@ str_ensure_byte_pos(VALUE str, long pos)
  *    s.byteindex('ooo') # => nil
  *
  *  When +object+ is a Regexp,
- *  returns the index of the first found substring matching +object+:
+ *  returns the index of the first found substring matching +object+;
+ *  updates {Regexp-related global variables}[rdoc-ref:Regexp@Global+Variables]:
  *
  *    s = 'foo'
  *    s.byteindex(/f/)   # => 0
+ *    $~                 # => #<MatchData "f">
  *    s.byteindex(/o/)   # => 1
  *    s.byteindex(/oo/)  # => 1
  *    s.byteindex(/ooo/) # => nil
+ *    $~                 # => nil
  *
  *  \Integer argument +offset+, if given, specifies the 0-based index
  *  of the byte where searching is to begin.
@@ -4992,7 +4995,7 @@ str_ensure_byte_pos(VALUE str, long pos)
  *    s.byteindex('o', -3) # => 1
  *    s.byteindex('o', -4) # => nil
  *
- *  Raises IndexError if +offset+ does not land of a character boundary:
+ *  Raises IndexError if the byte at +offset+ is not the first byte of a character:
  *
  *    s = "\uFFFF\uFFFF"       # => "\uFFFF\uFFFF"
  *    s.size                   # => 2 # Two 3-byte characters.