From fce4cae70ac33684244c0f1f053cf3e70a6fb6d7 Mon Sep 17 00:00:00 2001
From: Kevin Newton <kddnewton@gmail.com>
Date: Thu, 5 May 2022 11:45:25 -0400
Subject: [PATCH] Enable missing rules and more documentation

---
 .github/workflows/main.yml                    |   4 +-
 .rubocop.yml                                  |  20 +-
 README.md                                     |  24 ++
 config/rubocop.yml                            |   5 -
 lib/syntax_tree.rb                            |   4 +
 lib/syntax_tree/cli.rb                        |  14 +-
 lib/syntax_tree/language_server.rb            |   7 +-
 .../language_server/inlay_hints.rb            |   7 +
 lib/syntax_tree/node.rb                       | 391 ++++++++++--------
 lib/syntax_tree/parser.rb                     |  12 +-
 lib/syntax_tree/prettyprint.rb                |  22 +-
 lib/syntax_tree/visitor.rb                    |   3 +
 lib/syntax_tree/visitor/match_visitor.rb      |   2 +-
 .../visitor/pretty_print_visitor.rb           |   2 +-
 14 files changed, 304 insertions(+), 213 deletions(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 1ddaf0ae..7f5ac15c 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -37,7 +37,9 @@ jobs:
         bundler-cache: true
         ruby-version: '3.1'
     - name: Check
-      run: bundle exec rake check
+      run: |
+        bundle exec rake check
+        bundle exec rubocop
 
   automerge:
     name: AutoMerge
diff --git a/.rubocop.yml b/.rubocop.yml
index 5f005778..32db04ed 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -12,9 +12,6 @@ AllCops:
 
 Layout/LineLength:
   Max: 80
-  AllowedPatterns:
-  - '^\s*in '
-  - '^\s*location: Location'
 
 Lint/DuplicateBranch:
   Enabled: false
@@ -25,6 +22,9 @@ Lint/InterpolationCheck:
 Lint/MissingSuper:
   Enabled: false
 
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
 Metrics:
   Enabled: false
 
@@ -72,17 +72,3 @@ Style/PerlBackrefs:
 
 Style/SpecialGlobalVars:
   Enabled: false
-
-###
-
-Lint/AssignmentInCondition:
-  Enabled: false
-
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-Style/StringLiterals:
-  Enabled: false
diff --git a/README.md b/README.md
index ce22548c..d952d878 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,8 @@ It is built with only standard library dependencies. It additionally ships with
   - [ast](#ast)
   - [check](#check)
   - [format](#format)
+  - [json](#json)
+  - [match](#match)
   - [write](#write)
 - [Library](#library)
   - [SyntaxTree.read(filepath)](#syntaxtreereadfilepath)
@@ -34,6 +36,9 @@ It is built with only standard library dependencies. It additionally ships with
   - [textDocument/inlayHints](#textdocumentinlayhints)
   - [syntaxTree/visualizing](#syntaxtreevisualizing)
 - [Plugins](#plugins)
+- [Integration](#integration)
+  - [RuboCop](#rubocop)
+  - [VSCode](#vscode)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -395,6 +400,25 @@ Below are listed all of the "official" plugins hosted under the same GitHub orga
 * [SyntaxTree::JSON](https://github.com/ruby-syntax-tree/syntax_tree-json) for JSON.
 * [SyntaxTree::RBS](https://github.com/ruby-syntax-tree/syntax_tree-rbs) for the [RBS type language](https://github.com/ruby/rbs).
 
+When invoking the CLI, you pass through the list of plugins with the `--plugins` options to the commands that accept them. They should be a comma-delimited list. When the CLI first starts, it will require the files corresponding to those names.
+
+## Integration
+
+Syntax Tree's goal is to seemlessly integrate into your workflow. To this end, it provides a couple of additional tools beyond the CLI and the Ruby library.
+
+### RuboCop
+
+RuboCop and Syntax Tree serve different purposes, but there is overlap with some of RuboCop's functionality. Syntax Tree provides a RuboCop configuration file to disable rules that are redundant with Syntax Tree. To use this configuration file, add the following snippet to the top of your project's `.rubocop.yml`:
+
+```yaml
+inherit_gem:
+  syntax_tree: config/rubocop.yml
+```
+
+### VSCode
+
+To integrate Syntax Tree into VSCode, you should use the official VSCode extension [ruby-syntax-tree/vscode-syntax-tree](https://github.com/ruby-syntax-tree/vscode-syntax-tree).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-syntax-tree/syntax_tree.
diff --git a/config/rubocop.yml b/config/rubocop.yml
index d8d407ef..eff5aede 100644
--- a/config/rubocop.yml
+++ b/config/rubocop.yml
@@ -9,13 +9,8 @@ Layout:
 #
 # Users can always override these defaults in their own rubocop.yml files.
 # https://github.com/prettier/plugin-ruby/issues/825
-#
-# We're also explicitly allowing pattern matching to extend beyond the maximum
-# line length, since SyntaxTree prefers putting patterns on a single line.
 Layout/LineLength:
   Enabled: true
-  AllowedPatterns:
-  - '^\s*in '
 
 Style/MultilineIfModifier:
   Enabled: false
diff --git a/lib/syntax_tree.rb b/lib/syntax_tree.rb
index 632b062e..1f3b4f11 100644
--- a/lib/syntax_tree.rb
+++ b/lib/syntax_tree.rb
@@ -30,6 +30,10 @@
   end
 end
 
+# Syntax Tree is a suite of tools built on top of the internal CRuby parser. It
+# provides the ability to generate a syntax tree from source, as well as the
+# tools necessary to inspect and manipulate that syntax tree. It can be used to
+# build formatters, linters, language servers, and more.
 module SyntaxTree
   # This holds references to objects that respond to both #parse and #format
   # so that we can use them in the CLI.
diff --git a/lib/syntax_tree/cli.rb b/lib/syntax_tree/cli.rb
index a0b31212..3efa79cb 100644
--- a/lib/syntax_tree/cli.rb
+++ b/lib/syntax_tree/cli.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module SyntaxTree
+  # Syntax Tree ships with the `stree` CLI, which can be used to inspect and
+  # manipulate Ruby code. This module is responsible for powering that CLI.
   module CLI
     # A utility wrapper around colored strings in the output.
     class Color
@@ -46,7 +48,7 @@ def failure
 
     # An action of the CLI that prints out the AST for the given source.
     class AST < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         pp handler.parse(source)
       end
     end
@@ -100,7 +102,7 @@ def failure
 
     # An action of the CLI that prints out the doc tree IR for the given source.
     class Doc < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         formatter = Formatter.new(source, [])
         handler.parse(source).format(formatter)
         pp formatter.groups.first
@@ -109,7 +111,7 @@ def run(handler, filepath, source)
 
     # An action of the CLI that formats the input source and prints it out.
     class Format < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         puts handler.format(source)
       end
     end
@@ -117,7 +119,7 @@ def run(handler, filepath, source)
     # An action of the CLI that converts the source into its equivalent JSON
     # representation.
     class Json < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         object = Visitor::JSONVisitor.new.visit(handler.parse(source))
         puts JSON.pretty_generate(object)
       end
@@ -126,7 +128,7 @@ def run(handler, filepath, source)
     # An action of the CLI that outputs a pattern-matching Ruby expression that
     # would match the input given.
     class Match < Action
-      def run(handler, filepath, source)
+      def run(handler, _filepath, source)
         formatter = Formatter.new(source, [])
         Visitor::MatchVisitor.new(formatter).visit(handler.parse(source))
         formatter.flush
@@ -296,7 +298,7 @@ def run(argv)
       private
 
       def each_file(arguments)
-        if $stdin.tty?
+        if $stdin.tty? || arguments.any?
           arguments.each do |pattern|
             Dir
               .glob(pattern)
diff --git a/lib/syntax_tree/language_server.rb b/lib/syntax_tree/language_server.rb
index 3d518142..1e305cca 100644
--- a/lib/syntax_tree/language_server.rb
+++ b/lib/syntax_tree/language_server.rb
@@ -7,6 +7,11 @@
 require_relative "language_server/inlay_hints"
 
 module SyntaxTree
+  # Syntax Tree additionally ships with a language server conforming to the
+  # language server protocol. It can be invoked through the CLI by running:
+  #
+  #     stree lsp
+  #
   class LanguageServer
     attr_reader :input, :output
 
@@ -21,7 +26,7 @@ def run
           hash[uri] = File.binread(CGI.unescape(URI.parse(uri).path))
         end
 
-      while headers = input.gets("\r\n\r\n")
+      while (headers = input.gets("\r\n\r\n"))
         source = input.read(headers[/Content-Length: (\d+)/i, 1].to_i)
         request = JSON.parse(source, symbolize_names: true)
 
diff --git a/lib/syntax_tree/language_server/inlay_hints.rb b/lib/syntax_tree/language_server/inlay_hints.rb
index 02cbc6f5..69fc5ce4 100644
--- a/lib/syntax_tree/language_server/inlay_hints.rb
+++ b/lib/syntax_tree/language_server/inlay_hints.rb
@@ -2,6 +2,13 @@
 
 module SyntaxTree
   class LanguageServer
+    # This class provides inlay hints for the language server. It is loosely
+    # designed around the LSP spec, but existed before the spec was finalized so
+    # is a little different for now.
+    #
+    # For more information, see the spec here:
+    # https://github.com/microsoft/language-server-protocol/issues/956.
+    #
     class InlayHints < Visitor
       attr_reader :stack, :before, :after
 
diff --git a/lib/syntax_tree/node.rb b/lib/syntax_tree/node.rb
index 474d6d76..e5aa6b50 100644
--- a/lib/syntax_tree/node.rb
+++ b/lib/syntax_tree/node.rb
@@ -51,7 +51,7 @@ def deconstruct
       [start_line, start_char, start_column, end_line, end_char, end_column]
     end
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         start_line: start_line,
         start_char: start_char,
@@ -159,7 +159,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         lbrace: lbrace,
         statements: statements,
@@ -211,7 +211,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -262,7 +262,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         lbrace: lbrace,
         statements: statements,
@@ -317,7 +317,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -342,6 +342,8 @@ def format(q)
   # symbols (note that this includes dynamic symbols like
   # :"left-#{middle}-right").
   class Alias < Node
+    # Formats an argument to the alias keyword. For symbol literals it uses the
+    # value of the symbol directly to look like bare words.
     class AliasArgumentFormatter
       # [DynaSymbol | SymbolLiteral] the argument being passed to alias
       attr_reader :argument
@@ -393,7 +395,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { left: left, right: right, location: location, comments: comments }
     end
 
@@ -454,7 +456,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         collection: collection,
         index: index,
@@ -515,7 +517,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         collection: collection,
         index: index,
@@ -577,7 +579,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { arguments: arguments, location: location, comments: comments }
     end
 
@@ -625,7 +627,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location, comments: comments }
     end
 
@@ -661,7 +663,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -698,7 +700,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -748,7 +750,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -764,6 +766,7 @@ def format(q)
   #     [one, two, three]
   #
   class ArrayLiteral < Node
+    # Formats an array of multiple simple string literals into the %w syntax.
     class QWordsFormatter
       # [Args] the contents of the array
       attr_reader :contents
@@ -789,6 +792,7 @@ def format(q)
       end
     end
 
+    # Formats an array of multiple simple symbol literals into the %i syntax.
     class QSymbolsFormatter
       # [Args] the contents of the array
       attr_reader :contents
@@ -810,6 +814,28 @@ def format(q)
       end
     end
 
+    # Formats an array that contains only a list of variable references. To make
+    # things simpler, if there are a bunch, we format them all using the "fill"
+    # algorithm as opposed to breaking them into a ton of lines. For example,
+    #
+    #     [foo, bar, baz]
+    #
+    # instead of becoming:
+    #
+    #     [
+    #       foo,
+    #       bar,
+    #       baz
+    #     ]
+    #
+    # would instead become:
+    #
+    #     [
+    #       foo, bar,
+    #       baz
+    #     ]
+    #
+    # provided the line length was hit between `bar` and `baz`.
     class VarRefsFormatter
       # [Args] the contents of the array
       attr_reader :contents
@@ -835,6 +861,9 @@ def format(q)
       end
     end
 
+    # This is a special formatter used if the array literal contains no values
+    # but _does_ contain comments. In this case we do some special formatting to
+    # make sure the comments gets indented properly.
     class EmptyWithCommentsFormatter
       # [LBracket] the opening bracket
       attr_reader :lbracket
@@ -884,7 +913,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         lbracket: lbracket,
         contents: contents,
@@ -993,6 +1022,7 @@ def empty_with_comments?
   # and an optional array of positional matches that occur after the splat.
   # All of the in clauses above would create an AryPtn node.
   class AryPtn < Node
+    # Formats the optional splat of an array pattern.
     class RestFormatter
       # [VarField] the identifier that represents the remaining positionals
       attr_reader :value
@@ -1055,7 +1085,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         constant: constant,
         requireds: requireds,
@@ -1146,7 +1176,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { target: target, value: value, location: location, comments: comments }
     end
 
@@ -1208,7 +1238,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { key: key, value: value, location: location, comments: comments }
     end
 
@@ -1266,7 +1296,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -1304,7 +1334,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -1339,7 +1369,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -1352,6 +1382,7 @@ def format(q)
   # hash or bare hash. It first determines if every key in the hash can use
   # labels. If it can, it uses labels. Otherwise it uses hash rockets.
   module HashKeyFormatter
+    # Formats the keys of a hash literal using labels.
     class Labels
       def format_key(q, key)
         case key
@@ -1367,6 +1398,7 @@ def format_key(q, key)
       end
     end
 
+    # Formats the keys of a hash literal using hash rockets.
     class Rockets
       def format_key(q, key)
         case key
@@ -1440,7 +1472,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { assocs: assocs, location: location, comments: comments }
     end
 
@@ -1482,7 +1514,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { bodystmt: bodystmt, location: location, comments: comments }
     end
 
@@ -1530,7 +1562,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { statement: statement, location: location, comments: comments }
     end
 
@@ -1590,7 +1622,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         left: left,
         operator: operator,
@@ -1705,7 +1737,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { params: params, locals: locals, location: location, comments: comments }
     end
 
@@ -1749,7 +1781,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { name: name, location: location, comments: comments }
     end
 
@@ -1845,7 +1877,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statements: statements,
         rescue_clause: rescue_clause,
@@ -1891,6 +1923,7 @@ def format(q)
 
   # Responsible for formatting either a BraceBlock or a DoBlock.
   class BlockFormatter
+    # Formats the opening brace or keyword of a block.
     class BlockOpenFormatter
       # [String] the actual output that should be printed
       attr_reader :text
@@ -2083,7 +2116,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         lbrace: lbrace,
         block_var: block_var,
@@ -2282,7 +2315,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { arguments: arguments, location: location, comments: comments }
     end
 
@@ -2314,6 +2347,20 @@ def format(q)
     end
   end
 
+  # This is probably the most complicated formatter in this file. It's
+  # responsible for formatting chains of method calls, with or without arguments
+  # or blocks. In general, we want to go from something like
+  #
+  #     foo.bar.baz
+  #
+  # to
+  #
+  #     foo
+  #       .bar
+  #       .baz
+  #
+  # Of course there are a lot of caveats to that, including trailing operators
+  # when necessary, where comments are places, how blocks are aligned, etc.
   class CallChainFormatter
     # [Call | MethodAddBlock] the top of the call chain
     attr_reader :node
@@ -2348,7 +2395,7 @@ def format(q)
       # block. For more details, see
       # https://github.com/prettier/plugin-ruby/issues/863.
       parents = q.parents.take(4)
-      if parent = parents[2]
+      if (parent = parents[2])
         # If we're at a do_block, then we want to go one more level up. This is
         # because do blocks have BodyStmt nodes instead of just Statements
         # nodes.
@@ -2399,7 +2446,7 @@ def format_chain(q, children)
           # and a trailing operator.
           skip_operator = false
 
-          while child = children.pop
+          while (child = children.pop)
             case child
             in Call[
                  receiver: Call[message: { value: "where" }],
@@ -2556,7 +2603,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         receiver: receiver,
         operator: operator,
@@ -2666,7 +2713,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         keyword: keyword,
         value: value,
@@ -2731,7 +2778,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         value: value,
         operator: operator,
@@ -2820,7 +2867,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         constant: constant,
         superclass: superclass,
@@ -2885,7 +2932,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -2923,7 +2970,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         message: message,
         arguments: arguments,
@@ -3005,7 +3052,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         receiver: receiver,
         operator: operator,
@@ -3144,7 +3191,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, inline: inline, location: location }
     end
 
@@ -3190,7 +3237,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -3232,7 +3279,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         parent: parent,
         constant: constant,
@@ -3279,7 +3326,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         parent: parent,
         constant: constant,
@@ -3324,7 +3371,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { constant: constant, location: location, comments: comments }
     end
 
@@ -3360,7 +3407,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -3404,7 +3451,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         name: name,
         params: params,
@@ -3489,7 +3536,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         target: target,
         operator: operator,
@@ -3557,7 +3604,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -3623,7 +3670,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         target: target,
         operator: operator,
@@ -3698,7 +3745,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         keyword: keyword,
         block_var: block_var,
@@ -3778,7 +3825,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { left: left, right: right, location: location, comments: comments }
     end
 
@@ -3826,7 +3873,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { left: left, right: right, location: location, comments: comments }
     end
 
@@ -3913,7 +3960,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, quote: quote, location: location, comments: comments }
     end
 
@@ -4013,7 +4060,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         keyword: keyword,
         statements: statements,
@@ -4079,7 +4126,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         predicate: predicate,
         statements: statements,
@@ -4151,7 +4198,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
 
@@ -4186,7 +4233,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -4216,7 +4263,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -4248,7 +4295,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -4287,7 +4334,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         keyword: keyword,
         statements: statements,
@@ -4341,7 +4388,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -4384,7 +4431,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         value: value,
         arguments: arguments,
@@ -4444,7 +4491,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         parent: parent,
         operator: operator,
@@ -4490,7 +4537,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -4542,7 +4589,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         constant: constant,
         left: left,
@@ -4606,7 +4653,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         index: index,
         collection: collection,
@@ -4663,7 +4710,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -4677,6 +4724,9 @@ def format(q)
   #     { key => value }
   #
   class HashLiteral < Node
+    # This is a special formatter used if the hash literal contains no values
+    # but _does_ contain comments. In this case we do some special formatting to
+    # make sure the comments gets indented properly.
     class EmptyWithCommentsFormatter
       # [LBrace] the opening brace
       attr_reader :lbrace
@@ -4726,7 +4776,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { lbrace: lbrace, assocs: assocs, location: location, comments: comments }
     end
 
@@ -4821,7 +4871,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         beginning: beginning,
         location: location,
@@ -4897,7 +4947,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -4914,6 +4964,7 @@ def format(q)
   #     end
   #
   class HshPtn < Node
+    # Formats a key-value pair in a hash pattern. The value is optional.
     class KeywordFormatter
       # [Label] the keyword being used
       attr_reader :key
@@ -4940,6 +4991,7 @@ def format(q)
       end
     end
 
+    # Formats the optional double-splat from the pattern.
     class KeywordRestFormatter
       # [VarField] the parameter that matches the remaining keywords
       attr_reader :keyword_rest
@@ -4989,7 +5041,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         constant: constant,
         keywords: keywords,
@@ -5087,7 +5139,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -5104,7 +5156,7 @@ module ContainsAssignment
     def self.call(parent)
       queue = [parent]
 
-      while node = queue.shift
+      while (node = queue.shift)
         return true if [Assign, MAssign, OpAssign].include?(node.class)
         queue += node.child_nodes
       end
@@ -5339,7 +5391,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         predicate: predicate,
         statements: statements,
@@ -5389,7 +5441,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         predicate: predicate,
         truthy: truthy,
@@ -5528,7 +5580,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statement: statement,
         predicate: predicate,
@@ -5569,7 +5621,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -5616,7 +5668,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         pattern: pattern,
         statements: statements,
@@ -5675,7 +5727,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -5719,7 +5771,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -5764,7 +5816,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -5801,7 +5853,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { name: name, location: location, comments: comments }
     end
 
@@ -5847,7 +5899,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -5882,7 +5934,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -5918,7 +5970,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         params: params,
         statements: statements,
@@ -5989,7 +6041,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -6022,7 +6074,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -6055,7 +6107,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -6105,7 +6157,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { target: target, value: value, location: location, comments: comments }
     end
 
@@ -6152,7 +6204,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { call: call, block: block, location: location, comments: comments }
     end
 
@@ -6213,7 +6265,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location, comma: comma, comments: comments }
     end
 
@@ -6257,7 +6309,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { contents: contents, location: location, comments: comments }
     end
 
@@ -6313,7 +6365,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         constant: constant,
         bodystmt: bodystmt,
@@ -6380,7 +6432,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location, comments: comments }
     end
 
@@ -6429,7 +6481,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { arguments: arguments, location: location, comments: comments }
     end
 
@@ -6466,7 +6518,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -6512,7 +6564,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         target: target,
         operator: operator,
@@ -6621,6 +6673,8 @@ def self.break(q)
   #     def method(param) end
   #
   class Params < Node
+    # Formats the optional position of the parameters. This includes the label,
+    # as well as the default value.
     class OptionalFormatter
       # [Ident] the name of the parameter
       attr_reader :name
@@ -6644,6 +6698,8 @@ def format(q)
       end
     end
 
+    # Formats the keyword position of the parameters. This includes the label,
+    # as well as an optional default value.
     class KeywordFormatter
       # [Ident] the name of the parameter
       attr_reader :name
@@ -6670,6 +6726,8 @@ def format(q)
       end
     end
 
+    # Formats the keyword_rest position of the parameters. This can be the **nil
+    # syntax, the ... syntax, or the ** syntax.
     class KeywordRestFormatter
       # [:nil | ArgsForward | KwRestParam] the value of the parameter
       attr_reader :value
@@ -6764,7 +6822,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         location: location,
         requireds: requireds,
@@ -6845,7 +6903,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         lparen: lparen,
         contents: contents,
@@ -6896,7 +6954,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -6929,7 +6987,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { statements: statements, location: location, comments: comments }
     end
 
@@ -6974,7 +7032,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         beginning: beginning,
         elements: elements,
@@ -7029,7 +7087,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
 
@@ -7074,7 +7132,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         beginning: beginning,
         elements: elements,
@@ -7129,7 +7187,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -7161,7 +7219,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -7190,7 +7248,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -7215,7 +7273,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -7247,7 +7305,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -7286,7 +7344,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { beginning: beginning, parts: parts, location: location }
     end
   end
@@ -7319,7 +7377,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -7353,7 +7411,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -7394,7 +7452,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         beginning: beginning,
         ending: ending,
@@ -7499,7 +7557,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         exceptions: exceptions,
         variable: variable,
@@ -7593,7 +7651,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         keyword: keyword,
         exception: exception,
@@ -7660,7 +7718,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statement: statement,
         value: value,
@@ -7714,7 +7772,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { name: name, location: location, comments: comments }
     end
 
@@ -7751,7 +7809,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -7787,7 +7845,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { arguments: arguments, location: location, comments: comments }
     end
 
@@ -7823,7 +7881,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -7852,7 +7910,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -7891,7 +7949,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         target: target,
         bodystmt: bodystmt,
@@ -7993,7 +8051,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parser: parser, body: body, location: location, comments: comments }
     end
 
@@ -8115,7 +8173,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location }
     end
   end
@@ -8153,14 +8211,14 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { left: left, right: right, location: location, comments: comments }
     end
 
     def format(q)
       q.group do
         q.format(left)
-        q.text(' \\')
+        q.text(" \\")
         q.indent do
           q.breakable(force: true)
           q.format(right)
@@ -8198,7 +8256,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { variable: variable, location: location, comments: comments }
     end
 
@@ -8238,7 +8296,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { statements: statements, location: location, comments: comments }
     end
 
@@ -8296,7 +8354,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, quote: quote, location: location, comments: comments }
     end
 
@@ -8359,7 +8417,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { arguments: arguments, location: location, comments: comments }
     end
 
@@ -8412,7 +8470,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8442,7 +8500,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8476,7 +8534,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -8517,7 +8575,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         beginning: beginning,
         elements: elements,
@@ -8573,7 +8631,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8602,7 +8660,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8632,7 +8690,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8666,7 +8724,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { constant: constant, location: location, comments: comments }
     end
 
@@ -8704,7 +8762,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { constant: constant, location: location, comments: comments }
     end
 
@@ -8743,7 +8801,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8783,7 +8841,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -8821,7 +8879,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -8857,7 +8915,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statement: statement,
         parentheses: parentheses,
@@ -8924,7 +8982,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         operator: operator,
         statement: statement,
@@ -8944,6 +9002,9 @@ def format(q)
   #     undef method
   #
   class Undef < Node
+    # Undef accepts a variable number of arguments that can be either DynaSymbol
+    # or SymbolLiteral objects. For SymbolLiteral objects we descend directly
+    # into the value in order to have it come out as bare words.
     class UndefArgumentFormatter
       # [DynaSymbol | SymbolLiteral] the symbol to undefine
       attr_reader :node
@@ -8987,7 +9048,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { symbols: symbols, location: location, comments: comments }
     end
 
@@ -9046,7 +9107,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         predicate: predicate,
         statements: statements,
@@ -9092,7 +9153,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statement: statement,
         predicate: predicate,
@@ -9189,7 +9250,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         predicate: predicate,
         statements: statements,
@@ -9245,7 +9306,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statement: statement,
         predicate: predicate,
@@ -9311,7 +9372,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { left: left, right: right, location: location, comments: comments }
     end
 
@@ -9354,7 +9415,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -9398,7 +9459,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -9439,7 +9500,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -9479,7 +9540,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -9514,7 +9575,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { location: location, comments: comments }
     end
 
@@ -9565,7 +9626,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         arguments: arguments,
         statements: statements,
@@ -9646,7 +9707,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         predicate: predicate,
         statements: statements,
@@ -9702,7 +9763,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         statement: statement,
         predicate: predicate,
@@ -9771,7 +9832,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location, comments: comments }
     end
 
@@ -9811,7 +9872,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       {
         beginning: beginning,
         elements: elements,
@@ -9867,7 +9928,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location }
     end
   end
@@ -9896,7 +9957,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location }
     end
   end
@@ -9929,7 +9990,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { parts: parts, location: location, comments: comments }
     end
 
@@ -9967,7 +10028,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { arguments: arguments, location: location, comments: comments }
     end
 
@@ -10017,7 +10078,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
@@ -10053,7 +10114,7 @@ def child_nodes
 
     alias deconstruct child_nodes
 
-    def deconstruct_keys(keys)
+    def deconstruct_keys(_keys)
       { value: value, location: location, comments: comments }
     end
 
diff --git a/lib/syntax_tree/parser.rb b/lib/syntax_tree/parser.rb
index 233818bd..75d3c322 100644
--- a/lib/syntax_tree/parser.rb
+++ b/lib/syntax_tree/parser.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module SyntaxTree
+  # Parser is a subclass of the Ripper library that subscribes to the stream of
+  # tokens and nodes coming from the parser and builds up a syntax tree.
   class Parser < Ripper
     # A special parser error so that we can get nice syntax displays on the
     # error message when prettier prints out the results.
@@ -548,7 +550,7 @@ def on_aryptn(constant, requireds, rest, posts)
 
       # If there's the optional then keyword, then we'll delete that and use it
       # as the end bounds of the location.
-      if token = find_token(Kw, "then", consume: false)
+      if (token = find_token(Kw, "then", consume: false))
         tokens.delete(token)
         location = location.to(token.location)
       end
@@ -866,7 +868,7 @@ def on_call(receiver, operator, message)
     # :call-seq:
     #   on_case: (untyped value, untyped consequent) -> Case | RAssign
     def on_case(value, consequent)
-      if keyword = find_token(Kw, "case", consume: false)
+      if (keyword = find_token(Kw, "case", consume: false))
         tokens.delete(keyword)
 
         Case.new(
@@ -1691,7 +1693,7 @@ def on_hshptn(constant, keywords, keyword_rest)
       end
 
       # Delete the optional then keyword
-      if token = find_token(Kw, "then", consume: false)
+      if (token = find_token(Kw, "then", consume: false))
         parts << token
         tokens.delete(token)
       end
@@ -1805,7 +1807,7 @@ def on_in(pattern, statements, consequent)
       ending = consequent || find_token(Kw, "end")
 
       statements_start = pattern
-      if token = find_token(Kw, "then", consume: false)
+      if (token = find_token(Kw, "then", consume: false))
         tokens.delete(token)
         statements_start = token
       end
@@ -3422,7 +3424,7 @@ def on_when(arguments, statements, consequent)
       ending = consequent || find_token(Kw, "end")
 
       statements_start = arguments
-      if token = find_token(Kw, "then", consume: false)
+      if (token = find_token(Kw, "then", consume: false))
         tokens.delete(token)
         statements_start = token
       end
diff --git a/lib/syntax_tree/prettyprint.rb b/lib/syntax_tree/prettyprint.rb
index 27604a59..7fe64a56 100644
--- a/lib/syntax_tree/prettyprint.rb
+++ b/lib/syntax_tree/prettyprint.rb
@@ -375,7 +375,7 @@ class SingleLine
     #                This argument is a noop.
     # * +newline+ - Argument position expected to be here for compatibility.
     #               This argument is a noop.
-    def initialize(output, maxwidth = nil, newline = nil)
+    def initialize(output, _maxwidth = nil, _newline = nil)
       @output = Buffer.for(output)
       @target = @output
       @line_suffixes = Buffer::ArrayBuffer.new
@@ -397,7 +397,7 @@ def flush
     # They are all noop arguments.
     def breakable(
       separator = " ",
-      width = separator.length,
+      _width = separator.length,
       indent: nil,
       force: nil
     )
@@ -410,7 +410,7 @@ def break_parent
 
     # Appends +separator+ to the output buffer. +width+ is a noop here for
     # compatibility.
-    def fill_breakable(separator = " ", width = separator.length)
+    def fill_breakable(separator = " ", _width = separator.length)
       target << separator
     end
 
@@ -432,11 +432,11 @@ def trim
     # * +open_width+ - noop argument. Present for compatibility.
     # * +close_width+ - noop argument. Present for compatibility.
     def group(
-      indent = nil,
+      _indent = nil,
       open_object = "",
       close_object = "",
-      open_width = nil,
-      close_width = nil
+      _open_width = nil,
+      _close_width = nil
     )
       target << open_object
       yield
@@ -478,14 +478,14 @@ def line_suffix
     # Takes +indent+ arg, but does nothing with it.
     #
     # Yields to a block.
-    def nest(indent)
+    def nest(_indent)
       yield
     end
 
     # Add +object+ to the text to be output.
     #
     # +width+ argument is here for compatibility. It is a noop argument.
-    def text(object = "", width = nil)
+    def text(object = "", _width = nil)
       target << object
     end
   end
@@ -623,9 +623,9 @@ def self.format(
   #
   def self.singleline_format(
     output = "".dup,
-    maxwidth = nil,
-    newline = nil,
-    genspace = nil
+    _maxwidth = nil,
+    _newline = nil,
+    _genspace = nil
   )
     q = SingleLine.new(output)
     yield q
diff --git a/lib/syntax_tree/visitor.rb b/lib/syntax_tree/visitor.rb
index 18c4e88c..57794ddb 100644
--- a/lib/syntax_tree/visitor.rb
+++ b/lib/syntax_tree/visitor.rb
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module SyntaxTree
+  # Visitor is a parent class that provides the ability to walk down the tree
+  # and handle a subset of nodes. By defining your own subclass, you can
+  # explicitly handle a node type by defining a visit_* method.
   class Visitor
     # This is raised when you use the Visitor.visit_method method and it fails.
     # It is correctable to through DidYouMean.
diff --git a/lib/syntax_tree/visitor/match_visitor.rb b/lib/syntax_tree/visitor/match_visitor.rb
index ab88ae58..53caf4c5 100644
--- a/lib/syntax_tree/visitor/match_visitor.rb
+++ b/lib/syntax_tree/visitor/match_visitor.rb
@@ -56,7 +56,7 @@ def list(name, values)
         end
       end
 
-      def node(node, type)
+      def node(node, _type)
         items = []
         q.with_target(items) { yield }
 
diff --git a/lib/syntax_tree/visitor/pretty_print_visitor.rb b/lib/syntax_tree/visitor/pretty_print_visitor.rb
index 2010b35f..a45eec44 100644
--- a/lib/syntax_tree/visitor/pretty_print_visitor.rb
+++ b/lib/syntax_tree/visitor/pretty_print_visitor.rb
@@ -47,7 +47,7 @@ def list(_name, values)
         end
       end
 
-      def node(node, type)
+      def node(_node, type)
         q.group(2, "(", ")") do
           q.text(type)
           yield