[ruby/syntax_suggest] Update docs, clean up PR

Removes or updates mentions of Ripper

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

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"

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.""

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

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)

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
 

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:
   #

spec/syntax_suggest/unit/lex_all_spec.rb

@@ -17,9 +17,6 @@ module SyntaxSuggest
         end            # 9
       EOM
 
-      # raw_lex = Ripper.lex(source)
-      # expect(raw_lex.to_s).to_not include("dog")
-
       lex = LexAll.new(source: source)
       expect(lex.map(&:token).to_s).to include("dog")
       expect(lex.first.line).to eq(1)