[ruby/syntax_suggest] Update docs, clean up PR

Removes or updates mentions of Ripper

https://github.com/ruby/syntax_suggest/commit/08aaa3f50a

6 files changed, 26 insertions, 14 deletions

diff --git a/lib/syntax_suggest/api.rb b/lib/syntax_suggest/api.rb
index 59f47ee4f3..65660ec5e5 100644
--- a/lib/syntax_suggest/api.rb
+++ b/lib/syntax_suggest/api.rb
@@ -227,9 +227,6 @@ require_relative "lex_all"
 require_relative "code_line"
 require_relative "code_block"
 require_relative "block_expand"
-if !SyntaxSuggest.use_prism_parser?
-  require_relative "ripper_errors"
-end
 require_relative "priority_queue"
 require_relative "unvisited_lines"
 require_relative "around_block_scan"
diff --git a/lib/syntax_suggest/clean_document.rb b/lib/syntax_suggest/clean_document.rb
index 44aae262ef..0847a62e27 100644
--- a/lib/syntax_suggest/clean_document.rb
+++ b/lib/syntax_suggest/clean_document.rb
@@ -47,9 +47,9 @@ module SyntaxSuggest
   # ## Heredocs
   #
   # A heredoc is an way of defining a multi-line string. They can cause many
-  # problems. If left as a single line, Ripper would try to parse the contents
+  # problems. If left as a single line, the parser would try to parse the contents
   # as ruby code rather than as a string. Even without this problem, we still
-  # hit an issue with indentation
+  # hit an issue with indentation:
   #
   #    1 foo = <<~HEREDOC
   #    2  "Be yourself; everyone else is already taken.""
diff --git a/lib/syntax_suggest/code_block.rb b/lib/syntax_suggest/code_block.rb
index 61e7986da4..d842890300 100644
--- a/lib/syntax_suggest/code_block.rb
+++ b/lib/syntax_suggest/code_block.rb
@@ -81,7 +81,7 @@ module SyntaxSuggest
         # lines then the result cannot be invalid
         #
         # That means there's no reason to re-check all
-        # lines with ripper (which is expensive).
+        # lines with the parser (which is expensive).
         # Benchmark in commit message
         @valid = if lines.all? { |l| l.hidden? || l.empty? }
           true
diff --git a/lib/syntax_suggest/explain_syntax.rb b/lib/syntax_suggest/explain_syntax.rb
index 8de962c157..ee7d44ea00 100644
--- a/lib/syntax_suggest/explain_syntax.rb
+++ b/lib/syntax_suggest/explain_syntax.rb
@@ -2,6 +2,10 @@
 
 require_relative "left_right_lex_count"
 
+if !SyntaxSuggest.use_prism_parser?
+  require_relative "ripper_errors"
+end
+
 module SyntaxSuggest
   class GetParseErrors
     def self.errors(source)
@@ -25,8 +29,8 @@ module SyntaxSuggest
   #   # => "Unmatched keyword, missing `end' ?"
   #
   # When the error cannot be determined by lexical counting
-  # then ripper is run against the input and the raw ripper
-  # errors returned.
+  # then the parser is run against the input and the raw
+  # errors are returned.
   #
   # Example:
   #
@@ -101,7 +105,7 @@ module SyntaxSuggest
     # Returns an array of syntax error messages
     #
     # If no missing pairs are found it falls back
-    # on the original ripper error messages
+    # on the original error messages
     def errors
       if missing.empty?
         return GetParseErrors.errors(@code_lines.map(&:original).join)
diff --git a/lib/syntax_suggest/lex_all.rb b/lib/syntax_suggest/lex_all.rb
index e9509c4c3e..c16fbb52d3 100644
--- a/lib/syntax_suggest/lex_all.rb
+++ b/lib/syntax_suggest/lex_all.rb
@@ -3,10 +3,18 @@
 module SyntaxSuggest
   # Ripper.lex is not guaranteed to lex the entire source document
   #
-  # lex = LexAll.new(source: source)
-  # lex.each do |value|
-  #   puts value.line
-  # end
+  # This class guarantees the whole document is lex-ed by iteratively
+  # lexing the document where ripper stopped.
+  #
+  # Prism likely doesn't have the same problem. Once ripper support is removed
+  # we can likely reduce the complexity here if not remove the whole concept.
+  #
+  # Example usage:
+  #
+  #   lex = LexAll.new(source: source)
+  #   lex.each do |value|
+  #     puts value.line
+  #   end
   class LexAll
     include Enumerable
 
diff --git a/lib/syntax_suggest/ripper_errors.rb b/lib/syntax_suggest/ripper_errors.rb
index 48eb206e48..4e2bc90948 100644
--- a/lib/syntax_suggest/ripper_errors.rb
+++ b/lib/syntax_suggest/ripper_errors.rb
@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 module SyntaxSuggest
-  # Capture parse errors from ripper
+  # Capture parse errors from Ripper
+  #
+  # Prism returns the errors with their messages, but Ripper
+  # does not. To get them we must make a custom subclass.
   #
   # Example:
   #