Document new and revised methods

2 files changed, 154 insertions, 13 deletions

diff --git a/lib/bundler/cli/config.rb b/lib/bundler/cli/config.rb
index 22abc1f791..791f6070cf 100644
--- a/lib/bundler/cli/config.rb
+++ b/lib/bundler/cli/config.rb
@@ -92,6 +92,22 @@ module Bundler
       end
     end
 
+    # Checks whether `path` is already set and `path.system` is being set, and
+    # vice versa.
+    #
+    # @param  [String] name
+    #         the name of the option being set by the user.
+    #
+    # @param  [String] new_value
+    #         the value of the option being set by the user.
+    #
+    # @param  [String] scope
+    #         the scope of the option being set by the user (either `"local"` or
+    #         `"global"`).
+    #
+    # @return [Symbol] Either `:conflict` or `:no_conflict`, depending on whether
+    #         the options conflict.
+    #
     def resolve_system_path_conflicts(name, new_value, scope = "global")
       if name == "path.system" and Bundler.settings[:path] and new_value == "true"
         Bundler.ui.warn "`path` is already configured, so it will be unset."
@@ -106,6 +122,34 @@ module Bundler
       end
     end
 
+    # Check whether `with` or `without` groups have already been configured by
+    # the user. If so, check whether the user is setting a `without` or `with`
+    # group which conflicts with the previously set value in the appropriate
+    # scope. If there is a conflict, a warning including the conflicting
+    # group(s) is printed, and the previously set conflicting value is unset.
+    #
+    # Example: If `--local without foo bar baz` is set, and the user runs
+    # `bundle config --local with foo qux`, there will be a conflict, because
+    # `foo` is in the local `with` and `without` groups. If instead
+    # `bundle config --global with foo qux` is run, there will not be a
+    # conflict, because `foo` is in the local `without` group but the global
+    # `with` group.
+    #
+    # See config_spec.rb for other examples.
+    #
+    # @param  [String] name
+    #         the name of the option being set by the user.
+    #
+    # @param  [String] new_value
+    #         the value of the option being set by the user.
+    #
+    # @param  [String] scope
+    #         the scope of the option being set by the user (either `"local"` or
+    #         `"global"`).
+    #
+    # @return [Symbol] Either `:conflict` or `:no_conflict`, depending on whether
+    #         the options conflict.
+    #
     def resolve_group_conflicts(name, new_value, scope = "global")
       groups = new_value.split(":").map(&:to_sym)
 
@@ -144,36 +188,109 @@ module Bundler
       end
     end
 
+    # Deletes (sets to `nil`) the given configuration variable within the
+    # given scope. If the scope is `"global"`, only the local value is deleted,
+    # and vice versa. If the scope is `nil` or anything else, both the local
+    # and global values are unset.
+    #
+    # @param  [String] name
+    #         the name of the option being deleted.
+    #
+    # @param  [String] scope
+    #         the scope of the option being deleted (either `"local"` or
+    #         `"global"`).
+    #
+    # @return [Nil] The new value of `name`, which is `nil`.
+    #
     def delete_config(name, scope = nil)
       Bundler.settings.set_local(name, nil) unless scope == "global"
       Bundler.settings.set_global(name, nil) unless scope == "local"
     end
 
-    # group_conflict?: Detects conflicts in optional groups in consideration of scope.
-    # - `name` is the option name (`with` or `without`).
-    # - `groups` is an array of the name(s) of the included or excluded group(s).
-    # - `scope_prev` is the scope of the option previously set.
-    # - `scope_new` is the scope of the option the user is currently trying to set.
-    # NOTE: scope_prev and scope_new must be local or global.
+    # Detects conflicts in `with` and `without` groups in consideration of
+    # scope. Checks that the intersection of the two groups is nonempty and that
+    # the two groups have the same scope.
+    #
+    # @param  [String] name
+    #         the name (either `"with"` or `"without"`) of the already set group
+    #         with which we're comparing the user's groups.
+    #
+    # @param  [Array<Symbol>] groups
+    #         the name(s) of the included or excluded group(s) which the user is
+    #         trying to set.
+    #
+    # @param  [Symbol] scope_prev
+    #         the scope of the option previously set (either `:local` or `:global`).
+    #
+    # @param  [String] scope_new
+    #         the scope of the option the user is currently trying to set (either
+    #         `"local"` or `"global"`).
+    #
+    # @return [Boolean] Whether the `with` and `without` groups conflict.
+    #
     def groups_conflict?(name, groups, scope_prev, scope_new)
-      # We check that the intersection of the two groups is nonempty and that
-      # the two groups have the same scope.
       conflicts = conflicting_groups(name, groups, scope_prev, scope_new)
       conflicts && conflicts.size > 0 && scope_new.to_sym == scope_prev
     end
 
+    # Finds the conflicting (overlapping) groups in the list given by the user
+    # and those already stored in `Bundler.settings`.
+    #
+    # @param  [String] name
+    #         the name (either `"with"` or `"without"`) of the already set group
+    #         with which we're comparing the user's groups.
+    #
+    # @param  [Array<Symbol>] groups
+    #         the name(s) of the included or excluded group(s) which the user is
+    #         trying to set.
+    #
+    # @param  [Symbol] scope_prev
+    #         the scope of the option previously set (either `:local` or `:global`).
+    #
+    # @param  [String] scope_new
+    #         the scope of the option the user is currently trying to set (either
+    #         `"local"` or `"global"`).
+    #
+    # @return [Array<Symbol>] An array of the conflicting groups.
+    #
     def conflicting_groups(name, groups, scope_prev, scope_new)
       settings = Bundler.settings.send(name.to_sym, scope_prev)
       settings = (settings.map {|opt| opt.to_s.split(":").map(&:to_sym) }).flatten # TODO: refactor
       groups & settings
     end
 
-    def without_conflict?(group, scope)
-      groups_conflict?(:without, group, :local, scope) or groups_conflict?(:without, group, :global, scope)
+    # Determines whether the user's (`with`) groups conflict with the previously
+    # set `without` groups in `Bundler.settings`.
+    #
+    # @param  [Array<Symbol>] groups
+    #         the name(s) of the group(s) which the user is trying to set.
+    #
+    # @param  [String] scope
+    #         the scope of the option the user is currently trying to set (either
+    #         `"local"` or `"global"`).
+    #
+    # @return [Boolean] Whether there's a conflict in either the `local` or
+    #         `global` scope.
+    #
+    def without_conflict?(groups, scope)
+      groups_conflict?(:without, groups, :local, scope) or groups_conflict?(:without, groups, :global, scope)
     end
 
-    def with_conflict?(group, scope)
-      groups_conflict?(:with, group, :local, scope) or groups_conflict?(:with, group, :global, scope)
+    # Determines whether the user's (`without`) groups conflict with the
+    # previously set `with` groups in `Bundler.settings`.
+    #
+    # @param  [Array<Symbol>] groups
+    #         the name(s) of the group(s) which the user is trying to set.
+    #
+    # @param  [String] scope
+    #         the scope of the option the user is currently trying to set (either
+    #         `"local"` or `"global"`).
+    #
+    # @return [Boolean] Whether there's a conflict in either the `local` or
+    #         `global` scope.
+    #
+    def with_conflict?(groups, scope)
+      groups_conflict?(:with, groups, :local, scope) or groups_conflict?(:with, groups, :global, scope)
     end
   end
 end
diff --git a/lib/bundler/settings.rb b/lib/bundler/settings.rb
index d24686a4f3..afa76fcb79 100644
--- a/lib/bundler/settings.rb
+++ b/lib/bundler/settings.rb
@@ -125,15 +125,39 @@ module Bundler
       set_array(:with, array)
     end
 
+    # Finds the previously set `without` groups in the given scope.
+    #
+    # @param  [Symbol,Nil] scope
+    #         any of `:global`, `:local`, or `nil`.
+    #
+    # @return [Array<Symbol>] The previously set `without` groups.
+    #
     def without(scope = nil)
       groups_array(:without, scope)
     end
 
+    # Finds the previously set `with` groups in the given scope.
+    #
+    # @param  [Symbol,Nil] scope
+    #         any of `:global`, `:local`, or `nil`.
+    #
+    # @return [Array<Symbol>] The previously set `with` groups.
+    #
     def with(scope = nil)
       groups_array(:with, scope)
     end
 
-    # `group_type` is either :with or :without
+    # Finds the previously set groups of the given type and scope.
+    #
+    # @param  [Symbol] group_type
+    #         either `:with` or `:without`.
+    #
+    # @param  [Symbol,Nil] scope
+    #         any of `:global`, `:local`, or `nil`; otherwise, an error is
+    #         thrown.
+    #
+    # @return [Array<Symbol>] The previously set groups.
+    #
     def groups_array(group_type, scope)
       key = key_for(group_type)
       if scope.nil?