[DOC] Document AST.parse's keyword arguments

1 files changed, 36 insertions, 6 deletions

diff --git a/ast.rb b/ast.rb
index 2b803461ed..f3f72c747f 100644
--- a/ast.rb
+++ b/ast.rb
@@ -20,21 +20,47 @@
 module RubyVM::AbstractSyntaxTree
 
   #  call-seq:
-  #     RubyVM::AbstractSyntaxTree.parse(string) -> RubyVM::AbstractSyntaxTree::Node
+  #     RubyVM::AbstractSyntaxTree.parse(string, keep_script_lines: false, error_tolerant: false, keep_tokens: false) -> RubyVM::AbstractSyntaxTree::Node
   #
   #  Parses the given _string_ into an abstract syntax tree,
   #  returning the root node of that tree.
   #
-  #  SyntaxError is raised if the given _string_ is invalid syntax.
-  #
   #    RubyVM::AbstractSyntaxTree.parse("x = 1 + 2")
   #    # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-1:9>
+  #
+  #  If <tt>keep_script_lines: true</tt> option is provided, the text of the parsed
+  #  source is associated with nodes and is available via Node#script_lines.
+  #
+  #  If <tt>keep_tokens: true</tt> option is provided, Node#tokens are populated.
+  #
+  #  SyntaxError is raised if the given _string_ is invalid syntax. To overwrite this
+  #  behavior, <tt>error_tolerant: true</tt> can be provided. In this case, the parser
+  #  will produce a tree where expressions with syntax errors would be represented by
+  #  Node with <tt>type=:ERROR</tt>.
+  #
+  #     root = RubyVM::AbstractSyntaxTree.parse("x = 1; p(x; y=2")
+  #     # <internal:ast>:33:in `parse': syntax error, unexpected ';', expecting ')' (SyntaxError)
+  #     # x = 1; p(x; y=2
+  #     #           ^
+  #
+  #     root = RubyVM::AbstractSyntaxTree.parse("x = 1; p(x; y=2", error_tolerant: true)
+  #     # (SCOPE@1:0-1:15
+  #     #  tbl: [:x, :y]
+  #     #  args: nil
+  #     #  body: (BLOCK@1:0-1:15 (LASGN@1:0-1:5 :x (LIT@1:4-1:5 1)) (ERROR@1:7-1:11) (LASGN@1:12-1:15 :y (LIT@1:14-1:15 2))))
+  #     root.children.last.children
+  #     # [(LASGN@1:0-1:5 :x (LIT@1:4-1:5 1)),
+  #     #  (ERROR@1:7-1:11),
+  #     #  (LASGN@1:12-1:15 :y (LIT@1:14-1:15 2))]
+  #
+  #  Note that parsing continues even after the errored expresion.
+  #
   def self.parse string, keep_script_lines: false, error_tolerant: false, keep_tokens: false
     Primitive.ast_s_parse string, keep_script_lines, error_tolerant, keep_tokens
   end
 
   #  call-seq:
-  #     RubyVM::AbstractSyntaxTree.parse_file(pathname) -> RubyVM::AbstractSyntaxTree::Node
+  #     RubyVM::AbstractSyntaxTree.parse_file(pathname, keep_script_lines: false, error_tolerant: false, keep_tokens: false) -> RubyVM::AbstractSyntaxTree::Node
   #
   #   Reads the file from _pathname_, then parses it like ::parse,
   #   returning the root node of the abstract syntax tree.
@@ -44,13 +70,15 @@ module RubyVM::AbstractSyntaxTree
   #
   #     RubyVM::AbstractSyntaxTree.parse_file("my-app/app.rb")
   #     # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-31:3>
+  #
+  #   See ::parse for explanation of keyword argument meaning and usage.
   def self.parse_file pathname, keep_script_lines: false, error_tolerant: false, keep_tokens: false
     Primitive.ast_s_parse_file pathname, keep_script_lines, error_tolerant, keep_tokens
   end
 
   #  call-seq:
-  #     RubyVM::AbstractSyntaxTree.of(proc)   -> RubyVM::AbstractSyntaxTree::Node
-  #     RubyVM::AbstractSyntaxTree.of(method) -> RubyVM::AbstractSyntaxTree::Node
+  #     RubyVM::AbstractSyntaxTree.of(proc, keep_script_lines: false, error_tolerant: false, keep_tokens: false)   -> RubyVM::AbstractSyntaxTree::Node
+  #     RubyVM::AbstractSyntaxTree.of(method, keep_script_lines: false, error_tolerant: false, keep_tokens: false) -> RubyVM::AbstractSyntaxTree::Node
   #
   #   Returns AST nodes of the given _proc_ or _method_.
   #
@@ -63,6 +91,8 @@ module RubyVM::AbstractSyntaxTree
   #
   #     RubyVM::AbstractSyntaxTree.of(method(:hello))
   #     # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-3:3>
+  #
+  #   See ::parse for explanation of keyword argument meaning and usage.
   def self.of body, keep_script_lines: false, error_tolerant: false, keep_tokens: false
     Primitive.ast_s_of body, keep_script_lines, error_tolerant, keep_tokens
   end