   /// the variable `$0` will be replaced with the entire matched substring, `$1`
   /// with the first capture group, etc.
   ///
-  /// - note: To include the literal string "$1" in the replacement string,
-  ///   you must escape the "$": `\$1`.
+  /// For example, to include the literal string "$1" in the replacement string,
+  /// you must escape the "$": `\$1`.
   ///
   /// - requires: `pattern` is a valid regular expression. Invalid regular
   ///   expressions will cause this method to trap.

  /// the variable `$0` will be replaced with the entire matched substring, `$1`
  /// with the first capture group, etc.
  ///
  /// - note: To include the literal string "$1" in the replacement string,
  ///   you must escape the "$": `\$1`.
  ///
  /// - requires: `pattern` is a valid regular expression. Invalid regular
  ///   expressions will cause this method to trap.

  /// the variable `$0` will be replaced with the entire matched substring, `$1`
  /// with the first capture group, etc.
  ///
  /// For example, to include the literal string "$1" in the replacement string,
  /// you must escape the "$": `\$1`.
  ///
  /// - parameters:
  ///     - regex: A regular expression to match against `self`.
