From a56004c7456eabe7d8b6428e03657a949c4de638 Mon Sep 17 00:00:00 2001
From: Bundlerbot <bot@bundler.io>
Date: Wed, 6 Nov 2019 00:46:53 +0000
Subject: [PATCH] Merge #7394

7394: Add inline RDoc documentation r=hsbt a=zverok

Since Bundler became part of the standard library, it renders in Ruby's docs. Unfortunately, what renders there...  is not really helpful: https://docs.ruby-lang.org/en/master/Bundler.html

I've added rudimentary documentation for `Bundler` module and two of its most user-facing methods to solve this problem at least partially.

Co-authored-by: zverok <zverok.offline@gmail.com>
(cherry picked from commit a7cc4ec87f17e549a1f0fb9063c53a76889426d6)
---
 lib/bundler.rb                 | 64 ++++++++++++++++++++++++++++++++++
 lib/bundler/lockfile_parser.rb |  1 +
 2 files changed, 65 insertions(+)

diff --git a/lib/bundler.rb b/lib/bundler.rb
index 2ada6fe7891..809771a1687 100644
--- a/lib/bundler.rb
+++ b/lib/bundler.rb
@@ -14,6 +14,25 @@
 require_relative "bundler/current_ruby"
 require_relative "bundler/build_metadata"
 
+# Bundler provides a consistent environment for Ruby projects by
+# tracking and installing the exact gems and versions that are needed.
+#
+# Since Ruby 2.6, Bundler is a part of Ruby's standard library.
+#
+# Bunder is used by creating _gemfiles_ listing all the project dependencies
+# and (optionally) their versions and then using
+#
+#   require 'bundler/setup'
+#
+# or Bundler.setup to setup environment where only specified gems and their
+# specified versions could be used.
+#
+# See {Bundler website}[https://bundler.io/docs.html] for extensive documentation
+# on gemfiles creation and Bundler usage.
+#
+# As a standard library inside project, Bundler could be used for introspection
+# of loaded and required modules.
+#
 module Bundler
   environment_preserver = EnvironmentPreserver.new(ENV, EnvironmentPreserver::BUNDLER_KEYS)
   ORIGINAL_ENV = environment_preserver.restore
@@ -91,6 +110,33 @@ def bin_path
       end
     end
 
+    # Turns on the Bundler runtime. After +Bundler.setup+ call, all +load+ or
+    # +require+ of the gems would be allowed only if they are part of
+    # the Gemfile or Ruby's standard library. If the versions specified
+    # in Gemfile, only those versions would be loaded.
+    #
+    # Assuming Gemfile
+    #
+    #    gem 'first_gem', '= 1.0'
+    #    group :test do
+    #      gem 'second_gem', '= 1.0'
+    #    end
+    #
+    # The code using Bundler.setup works as follows:
+    #
+    #    require 'third_gem' # allowed, required from global gems
+    #    require 'first_gem' # allowed, loads the last installed version
+    #    Bundler.setup
+    #    require 'fourth_gem' # fails with LoadError
+    #    require 'second_gem' # loads exactly version 1.0
+    #
+    # +Bundler.setup+ can be called only once, all subsequent calls are no-op.
+    #
+    # If _groups_ list is provided, only gems from specified groups would
+    # be allowed (gems specified outside groups belong to special +:default+ group).
+    #
+    # To require all gems from Gemfile (or only some groups), see Bundler.require.
+    #
     def setup(*groups)
       # Return if all groups are already loaded
       return @setup if defined?(@setup) && @setup
@@ -107,6 +153,24 @@ def setup(*groups)
       end
     end
 
+    # Setups Bundler environment (see Bundler.setup) if it is not already set,
+    # and loads all gems from groups specified. Unlike ::setup, can be called
+    # multiple times with different groups (if they were allowed by setup).
+    #
+    # Assuming Gemfile
+    #
+    #    gem 'first_gem', '= 1.0'
+    #    group :test do
+    #      gem 'second_gem', '= 1.0'
+    #    end
+    #
+    # The code will work as follows:
+    #
+    #    Bundler.setup # allow all groups
+    #    Bundler.require(:default) # requires only first_gem
+    #    # ...later
+    #    Bundler.require(:test)   # requires second_gem
+    #
     def require(*groups)
       setup(*groups).require(*groups)
     end
diff --git a/lib/bundler/lockfile_parser.rb b/lib/bundler/lockfile_parser.rb
index 5658ec12050..caabd524d49 100644
--- a/lib/bundler/lockfile_parser.rb
+++ b/lib/bundler/lockfile_parser.rb
@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+#--
 # Some versions of the Bundler 1.1 RC series introduced corrupted
 # lockfiles. There were two major problems:
 #