Added doc for source

3 files changed, 59 insertions, 7 deletions

diff --git a/lib/bundler/dsl.rb b/lib/bundler/dsl.rb
index b1308833..04ef641b 100644
--- a/lib/bundler/dsl.rb
+++ b/lib/bundler/dsl.rb
@@ -128,7 +128,7 @@ module Bundler
     def source(source, *args, &blk)
       options = args.last.is_a?(Hash) ? args.pop.dup : {}
       options = normalize_hash(options)
-      if options && options.key?("type")
+      if options.key?("type")
         options["type"] = options["type"].to_s
         unless Plugin.source?(options["type"])
           raise "No sources available for #{options["type"]}"
diff --git a/lib/bundler/plugin.rb b/lib/bundler/plugin.rb
index abeb854a..4dbf20b2 100644
--- a/lib/bundler/plugin.rb
+++ b/lib/bundler/plugin.rb
@@ -103,7 +103,7 @@ module Bundler
     def source(name)
       raise UnknownSourceError, "Source #{name} not found" unless source? name
 
-      load_plugin index.source_plugin name unless @sources.key? name
+      load_plugin(index.source_plugin(name)) unless @sources.key? name
 
       @sources[name]
     end
@@ -168,7 +168,7 @@ module Bundler
         raise MalformattedPlugin, "#{e.class}: #{e.message}"
       end
 
-      if optional && @sources.keys.any? { |s| source? s }
+      if optional && @sources.keys.any? {|s| source? s }
         Bundler.rm_rf(path)
       else
         index.register_plugin name, path.to_s, @commands.keys, @sources.keys
diff --git a/lib/bundler/plugin/api/source.rb b/lib/bundler/plugin/api/source.rb
index b33852e9..b2cb22fe 100644
--- a/lib/bundler/plugin/api/source.rb
+++ b/lib/bundler/plugin/api/source.rb
@@ -5,6 +5,19 @@ require "digest/sha1"
 module Bundler
   module Plugin
     class API
+      # This class provides the base to build source plugins
+      # All the method here are require to build a source plugin (except
+      # `uri_hash`, `gem_install_dir`; they are helpers).
+      #
+      # Defaults for methods, where ever possible are provided which is
+      # expected to work. But, all source plugins have to override `fetch_gemfiles`
+      # and `install`. Defaults are also not provided for `remote!`, `cache!`
+      # and `unlock!`.
+      #
+      # The defaults shall work for most situations but nevertheless they can
+      # be (preferably should be) overridden as per the plugins' needs safely
+      # (as long as they behave as expected).
+      # On overriding `initialize` you should call super first.
       module Source
         attr_reader :uri, :options
         attr_accessor :dependency_names
@@ -16,22 +29,40 @@ module Bundler
           @type = opts["type"]
         end
 
-        def installed?
-          File.directory?(install_path)
-        end
-
+        # This is used by the default `spec` method to constructs the
+        # Specification objects for the gems and versions that can be installed
+        # by this source plugin.
+        #
+        # Note: If the spec method is overridden, this function is not necessary
+        #
+        # @return [Array<String>] paths of the gemfiles that can be installed
         def fetch_gemfiles
           []
         end
 
+        # Options to be saved in the lockfile so that the source plugin is able
+        # to check out same version of gem later.
+        #
+        # There options are passed when the source plugin is created from the
+        # lock file.
+        #
+        # @return [Hash]
         def options_to_lock
           {}
         end
 
+        # Install the gem specified by the spec at appropriate path.
+        # `install_path` provides a sufficient default, if the source can only
+        # satisfy one gem,  but is not binding.
+        #
+        # @return [String] post installation message (if any)
         def install(spec, opts)
           raise MalformattedPlugin, "Source plugins need to override the install method."
         end
 
+        # A default installation path to install a single gem. If the source
+        # servers multiple gems, it's not of much use and the source should one
+        # of its own.
         def install_path
           @install_path ||=
             begin
@@ -41,6 +72,18 @@ module Bundler
             end
         end
 
+        # Parses the gemfiles to find the specs for the gems that can be
+        # satisfied by the source.
+        #
+        # Few important points to keep in mind:
+        #   - If the gems are not installed then it shall return specs for all
+        #   the gems it can satisfy
+        #   - If gem is installed (that is to be detected by the plugin itself)
+        #   then it shall return at least the specs that are installed.
+        #   - The `loaded_from` for each of the specs shall be correct (it is
+        #   used to find the load path)
+        #
+        # @return [Bundler::Index] index containing the specs
         def specs
           files = fetch_gemfiles
 
@@ -57,9 +100,14 @@ module Bundler
           end
         end
 
+        # Set internal representation to fetch the gems/specs from remote.
+        #
+        # It is preferable not to use any remote calls if this method is not
+        # called.
         def remote!
         end
 
+        # Set internal representation to fetch the gems/specs from cache.
         def cache!
         end
 
@@ -70,6 +118,10 @@ module Bundler
           other.is_a?(self.class) && uri == other.uri
         end
 
+        def installed?
+          File.directory?(install_path)
+        end
+
         def unmet_deps
           specs.unmet_dependency_names
         end