From c8d07edf0fa333d6ce836beb795ad14a7c6b5303 Mon Sep 17 00:00:00 2001
From: Utkarsh Gupta <utkarsh@debian.org>
Date: Sun, 23 Aug 2020 04:10:54 +0530
Subject: [PATCH] Write documentation and update the docs/

Update documentation to include a good and
a bad example. And also update the docs/.

Signed-off-by: Utkarsh Gupta <utkarsh@debian.org>
---
 docs/modules/ROOT/pages/cops_packaging.adoc   | 15 ++++++++-
 .../cop/packaging/bundler_setup_in_tests.rb   | 33 ++++++++++++++++---
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/modules/ROOT/pages/cops_packaging.adoc b/docs/modules/ROOT/pages/cops_packaging.adoc
index eb94ddf..2bf2c80 100644
--- a/docs/modules/ROOT/pages/cops_packaging.adoc
+++ b/docs/modules/ROOT/pages/cops_packaging.adoc
@@ -12,7 +12,20 @@
 | -
 |===
 
-TODO: Write cop description and example of bad / good code.
+This cop flags the `require "bundler/setup"` calls if they're
+made from inside the tests directory.
+
+=== Examples
+
+[source,ruby]
+----
+# bad
+require "foo"
+require "bundler/setup"
+
+# good
+require "foo"
+----
 
 == Packaging/GemspecGit
 
diff --git a/lib/rubocop/cop/packaging/bundler_setup_in_tests.rb b/lib/rubocop/cop/packaging/bundler_setup_in_tests.rb
index 8a49487..3ced57a 100644
--- a/lib/rubocop/cop/packaging/bundler_setup_in_tests.rb
+++ b/lib/rubocop/cop/packaging/bundler_setup_in_tests.rb
@@ -2,15 +2,26 @@
 
 require "rubocop/packaging/lib_helper_module"
 
-module RuboCop
-  module Cop
-    module Packaging
-      # TODO: Write cop description and example of bad / good code.
+module RuboCop # :nodoc:
+  module Cop # :nodoc:
+    module Packaging # :nodoc:
+      # This cop flags the `require "bundler/setup"` calls if they're
+      # made from inside the tests directory.
+      #
+      # @example
+      #
+      #   # bad
+      #   require "foo"
+      #   require "bundler/setup"
+      #
+      #   # good
+      #   require "foo"
       #
       class BundlerSetupInTests < Base
         include RuboCop::Packaging::LibHelperModule
 
-        # TODO: Write documentation.
+        # This is the message that will be displayed when RuboCop::Packaging finds
+        # an offense of using `require "bundler/setup"` in the tests directory.
         MSG = "Avoid using `bundler/setup` in your tests."
 
         def_node_matcher :bundler_setup?, <<~PATTERN
@@ -18,21 +29,33 @@ class BundlerSetupInTests < Base
             (str #bundler_setup_in_test_dir?))
         PATTERN
 
+        # Extended from the Base class.
+        # More about the `#on_new_investigation` method can be found here:
+        # https://github.com/rubocop-hq/rubocop/blob/343f62e4555be0470326f47af219689e21c61a37/lib/rubocop/cop/base.rb
+        #
+        # Processing of the AST happens here.
         def on_new_investigation
           @file_path = processed_source.file_path
           @file_directory = File.dirname(@file_path)
         end
 
+        # Extended from AST::Traversal.
+        # More about the `#on_send` method can be found here:
+        # https://github.com/rubocop-hq/rubocop-ast/blob/08d0f49a47af1e9a30a6d8f67533ba793c843d67/lib/rubocop/ast/traversal.rb#L112
         def on_send(node)
           return unless bundler_setup?(node)
 
           add_offense(node)
         end
 
+        # This method is called from inside `#def_node_matcher`.
+        # It flags an offense if the `require "bundler/setup"`
+        # call is made from the tests directory.
         def bundler_setup_in_test_dir?(str)
           str.eql?("bundler/setup") && falls_in_test_dir?
         end
 
+        # This method determines if the call is made *from* the tests directory.
         def falls_in_test_dir?
           %w[spec specs test tests].any? { |dir| File.expand_path(@file_directory).start_with?("#{root_dir}/#{dir}") }
         end