Update documentation for Ripper.{lex,tokenize,sexp,sexp_raw} [ci skip]

2 files changed, 17 insertions, 0 deletions

diff --git a/ext/ripper/lib/ripper/lexer.rb b/ext/ripper/lib/ripper/lexer.rb
index e7a0787c7a..052aa52de9 100644
--- a/ext/ripper/lib/ripper/lexer.rb
+++ b/ext/ripper/lib/ripper/lexer.rb
@@ -14,6 +14,11 @@ require 'ripper/core'
 class Ripper
 
   # Tokenizes the Ruby program and returns an array of strings.
+  # The +filename+ and +lineno+ arguments are mostly ignored, since the
+  # return value is just the tokenized input.
+  # By default, this method does not handle syntax errors in +src+,
+  # ignoring tokens after the syntax error.  Use the +raise_errors+ keyword
+  # to raise a SyntaxError for an error in +src+.
   #
   #   p Ripper.tokenize("def m(a) nil end")
   #      # => ["def", " ", "m", "(", "a", ")", " ", "nil", " ", "end"]
@@ -32,6 +37,10 @@ class Ripper
   # Tokenizes the Ruby program and returns an array of an array,
   # which is formatted like
   # <code>[[lineno, column], type, token, state]</code>.
+  # The +filename+ argument is mostly ignored.
+  # By default, this method does not handle syntax errors in +src+,
+  # ignoring tokens after the syntax error.  Use the +raise_errors+ keyword
+  # to raise a SyntaxError for an error in +src+.
   #
   #   require 'ripper'
   #   require 'pp'
diff --git a/ext/ripper/lib/ripper/sexp.rb b/ext/ripper/lib/ripper/sexp.rb
index 27b86e4af0..b1d553b1da 100644
--- a/ext/ripper/lib/ripper/sexp.rb
+++ b/ext/ripper/lib/ripper/sexp.rb
@@ -17,6 +17,10 @@ class Ripper
   # Parses +src+ and create S-exp tree.
   # Returns more readable tree rather than Ripper.sexp_raw.
   # This method is mainly for developer use.
+  # The +filename+ argument is mostly ignored.
+  # By default, this method does not handle syntax errors in +src+,
+  # returning +nil+ in such cases. Use the +raise_errors+ keyword
+  # to raise a SyntaxError for an error in +src+.
   #
   #   require 'ripper'
   #   require 'pp'
@@ -43,6 +47,10 @@ class Ripper
   # [EXPERIMENTAL]
   # Parses +src+ and create S-exp tree.
   # This method is mainly for developer use.
+  # The +filename+ argument is mostly ignored.
+  # By default, this method does not handle syntax errors in +src+,
+  # returning +nil+ in such cases. Use the +raise_errors+ keyword
+  # to raise a SyntaxError for an error in +src+.
   #
   #   require 'ripper'
   #   require 'pp'