13 files changed, 9 insertions, 37 deletions
diff --git a/doc/strscan/.document b/doc/strscan/.document
new file mode 100644
index 0000000000..b8085a8474
--- /dev/null
+++ b/doc/strscan/.document
@@ -0,0 +1 @@
+helper_methods.md
diff --git a/doc/strscan/link_refs.txt b/doc/strscan/link_refs.txt
index 19f6f7ce5c..04c4419982 100644
--- a/doc/strscan/link_refs.txt
+++ b/doc/strscan/link_refs.txt
@@ -1,5 +1,5 @@
 [1]: rdoc-ref:StringScanner@Stored+String
-[2]: rdoc-ref:StringScanner@Byte+Position+-28Position-29
+[2]: rdoc-ref:StringScanner@Byte+Position+Position
 [3]: rdoc-ref:StringScanner@Target+Substring
 [4]: rdoc-ref:StringScanner@Setting+the+Target+Substring
 [5]: rdoc-ref:StringScanner@Traversing+the+Target+Substring
diff --git a/doc/strscan/methods/get_byte.md b/doc/strscan/methods/get_byte.md
index 3208d77158..775226638e 100644
--- a/doc/strscan/methods/get_byte.md
+++ b/doc/strscan/methods/get_byte.md
@@ -1,6 +1,3 @@
-call-seq:
-  get_byte -> byte_as_character or nil
-
 Returns the next byte, if available:
 
 - If the [position][2]
diff --git a/doc/strscan/methods/get_charpos.md b/doc/strscan/methods/get_charpos.md
index 954fcf5b44..4de07897dc 100644
--- a/doc/strscan/methods/get_charpos.md
+++ b/doc/strscan/methods/get_charpos.md
@@ -1,6 +1,3 @@
-call-seq:
-  charpos -> character_position
-
 Returns the [character position][7] (initially zero),
 which may be different from the [byte position][2]
 given by method #pos:
diff --git a/doc/strscan/methods/get_pos.md b/doc/strscan/methods/get_pos.md
index 81bbb2345e..56b1636812 100644
--- a/doc/strscan/methods/get_pos.md
+++ b/doc/strscan/methods/get_pos.md
@@ -1,6 +1,3 @@
-call-seq:
-  pos -> byte_position
-
 Returns the integer [byte position][2],
 which may be different from the [character position][7]:
 
diff --git a/doc/strscan/methods/getch.md b/doc/strscan/methods/getch.md
index 3dd70e4c5b..ede1d2b071 100644
--- a/doc/strscan/methods/getch.md
+++ b/doc/strscan/methods/getch.md
@@ -1,6 +1,3 @@
-call-seq:
-  getch -> character or nil
-
 Returns the next (possibly multibyte) character,
 if available:
 
diff --git a/doc/strscan/methods/scan.md b/doc/strscan/methods/scan.md
index 22ddd368b6..805c797913 100644
--- a/doc/strscan/methods/scan.md
+++ b/doc/strscan/methods/scan.md
@@ -1,6 +1,3 @@
-call-seq:
-  scan(pattern) -> substring or nil
-
 Attempts to [match][17] the given `pattern`
 at the beginning of the [target substring][3].
 
diff --git a/doc/strscan/methods/scan_until.md b/doc/strscan/methods/scan_until.md
index 9a8c7c02f6..5fb2912a1b 100644
--- a/doc/strscan/methods/scan_until.md
+++ b/doc/strscan/methods/scan_until.md
@@ -1,6 +1,3 @@
-call-seq:
-  scan_until(pattern) -> substring or nil
-
 Attempts to [match][17] the given `pattern`
 anywhere (at any [position][2]) in the [target substring][3].
 
diff --git a/doc/strscan/methods/set_pos.md b/doc/strscan/methods/set_pos.md
index 3b7abe65e3..6a43edeb41 100644
--- a/doc/strscan/methods/set_pos.md
+++ b/doc/strscan/methods/set_pos.md
@@ -1,7 +1,3 @@
-call-seq:
-  pos = n -> n
-  pointer = n -> n
-
 Sets the [byte position][2] and the [character position][11];
 returns `n`.
 
diff --git a/doc/strscan/methods/skip.md b/doc/strscan/methods/skip.md
index 10a329e0e4..7e924b624b 100644
--- a/doc/strscan/methods/skip.md
+++ b/doc/strscan/methods/skip.md
@@ -1,6 +1,3 @@
-call-seq:
-  skip(pattern) match_size or nil
-
 Attempts to [match][17] the given `pattern`
 at the beginning of the [target substring][3];
 
diff --git a/doc/strscan/methods/skip_until.md b/doc/strscan/methods/skip_until.md
index b7dacf6da1..a0ffab0b84 100644
--- a/doc/strscan/methods/skip_until.md
+++ b/doc/strscan/methods/skip_until.md
@@ -1,13 +1,11 @@
-call-seq:
-  skip_until(pattern) -> matched_substring_size or nil
-
 Attempts to [match][17] the given `pattern`
-anywhere (at any [position][2]) in the [target substring][3];
-does not modify the positions.
+anywhere (at any [position][2]) in the [target substring][3].
 
 If the match attempt succeeds:
 
 - Sets [match values][9].
+- Sets the [byte position][2] to the end of the matched substring;
+  may adjust the [character position][7].
 - Returns the size of the matched substring.
 
 ```rb
@@ -42,6 +40,7 @@ If the match attempt fails:
 
 - Clears match values.
 - Returns `nil`.
+- Does not update positions.
 
 ```rb
 scanner.skip_until(/nope/)     # => nil
diff --git a/doc/strscan/methods/terminate.md b/doc/strscan/methods/terminate.md
index b03b37d2a2..27f7d41cb1 100644
--- a/doc/strscan/methods/terminate.md
+++ b/doc/strscan/methods/terminate.md
@@ -1,6 +1,3 @@
-call-seq:
-  terminate -> self
-
 Sets the scanner to end-of-string;
 returns +self+:
 
diff --git a/doc/strscan/strscan.md b/doc/strscan/strscan.md
index 1211a687c2..bbdeccd75e 100644
--- a/doc/strscan/strscan.md
+++ b/doc/strscan/strscan.md
@@ -37,7 +37,7 @@ Some examples here assume that certain helper methods are defined:
 - `match_values_cleared?(scanner)`:
   Returns whether the scanner's [match values][9] are cleared.
 
-See examples [here][ext/strscan/helper_methods_md.html].
+See examples at [helper methods](doc/strscan/helper_methods.md).
 
 ## The `StringScanner` \Object
 
@@ -204,7 +204,7 @@ put_situation(scanner)
 
 ## Target Substring
 
-The target substring is the the part of the [stored string][1]
+The target substring is the part of the [stored string][1]
 that extends from the current [byte position][2] to the end of the stored string;
 it is always either:
 
@@ -417,7 +417,7 @@ Each of these methods returns a captured match value:
 | Method          | Return After Match                      | Return After No Match |
 |-----------------|-----------------------------------------|-----------------------|
 | #size           | Count of captured substrings.           | +nil+.                |
-| #[](n)          | <tt>n</tt>th captured substring.        | +nil+.                |
+| #\[\](n)        | <tt>n</tt>th captured substring.        | +nil+.                |
 | #captures       | Array of all captured substrings.       | +nil+.                |
 | #values_at(*n)  | Array of specified captured substrings. | +nil+.                |
 | #named_captures | Hash of named captures.                 | <tt>{}</tt>.          |