Added documentations to the functions

3 files changed, 56 insertions, 2 deletions

diff --git a/lib/bundler/plugin.rb b/lib/bundler/plugin.rb
index e92689dd87..a829084498 100644
--- a/lib/bundler/plugin.rb
+++ b/lib/bundler/plugin.rb
@@ -6,6 +6,13 @@ module Bundler
 
     class << self
 
+      # Installs a new plugin by the given name
+      #
+      #
+      # @param [String] name the name of plugin to be installed
+      # @param [Hash] options various parameters as described in description
+      # @option options [String] :source rubygems source to fetch the plugin gem from
+      # @option options [String] :version (optional) the version of the plugin to install
       def install(name, options)
         require "bundler/plugin/installer.rb"
 
@@ -24,26 +31,41 @@ module Bundler
         Bundler.ui.error "Failed to install plugin #{name}: #{e.message}\n  #{e.backtrace.join("\n  ")}"
       end
 
+      # Checks if the gem is good to be a plugin
+      #
+      # At present it just checks whether it contains plugin.rb file
+      #
+      # @param [Pathname] plugin_path the path plugin is installed at
+      #
+      # @raise [Error] if plugin.rb file is not found
       def validate_plugin! plugin_path
         unless File.file? plugin_path.join("plugin.rb")
           raise "plugin.rb was not found in the plugin gem!"
         end
       end
 
+      # Runs the plugin.rb file, records the plugin actions it registers for and
+      # then passes the data to index to be stored
+      #
+      # @param [String] name the name of the plugin
+      # @param [Pathname] path the path where the plugin is installed at
       def register_plugin name, path
         require path.join("plugin.rb") # this shall latter be used to find the actions the plugin performs
 
         index.register_plugin name, path
       end
 
+      # The index object used to store the details about the plugin
       def index
         @index ||= Index.new
       end
 
+      # The directory root to all plugin related data
       def root
         @root ||= Bundler.user_bundle_path.join("plugin")
       end
 
+      # The cache directory for plugin stuffs
       def cache
         @cache ||= root.join("cache")
       end
diff --git a/lib/bundler/plugin/index.rb b/lib/bundler/plugin/index.rb
index d548475064..4f0a57ee05 100644
--- a/lib/bundler/plugin/index.rb
+++ b/lib/bundler/plugin/index.rb
@@ -2,6 +2,9 @@
 require "yaml"
 
 module Bundler
+  # Manages which plugins are installed and their sources. This also is supposed to map
+  # which plugin does what (currently the features are not implemented so this class is
+  # now just a stub class).
   class Plugin::Index
 
     def initialize
@@ -10,6 +13,7 @@ module Bundler
       load_index
     end
 
+    # Reads the index file from the directory and initializes the instance variables.
     def load_index
       SharedHelpers.filesystem_access(index_file, :read) do |index_f|
         valid_file = index_f && index_f.exist? && !index_f.size.zero?
@@ -19,6 +23,8 @@ module Bundler
       end
     end
 
+    # Should be called when any of the instance variables change. Stores the instance
+    # variables in YAML format. (The instance variables are supposed to be just String key value pairs)
     def save_index
       index = {
         :plugin_sources => @plugin_sources
@@ -30,12 +36,18 @@ module Bundler
       end
     end
 
+    # This function is to be called when a new plugin is installed. This function shall add
+    # the functions of the plugin to existing maps and also the name to source location.
+    #
+    # @param [String] name of the plugin to be registered
+    # @param [String] path where the plugin is installed
     def register_plugin(name, path)
       @plugin_sources[name] = path
 
       save_index
     end
 
+    # Path where the index file is stored
     def index_file
       Plugin.root.join("index")
     end
diff --git a/lib/bundler/plugin/installer.rb b/lib/bundler/plugin/installer.rb
index 8477ffad2c..5c23e3af70 100644
--- a/lib/bundler/plugin/installer.rb
+++ b/lib/bundler/plugin/installer.rb
@@ -1,10 +1,24 @@
 #frozen_string_literal: true
 
 module Bundler
+  # Handles the installation of plugin in appropriate directories.
+  #
+  # This class is supposed to be wrapper over the existing gem installation infra
+  # but currently it itself handles everything as the Source's subclasses (e.g. Source::RubyGems)
+  # are heavily dependent on the Gemfile.
+  #
+  # @todo: Remove the dependencies of Source's subclasses and try to use the Bundler sources directly. This will reduce the redundancies.
   class Plugin::Installer
 
     # Installs the plugin and returns the path where the plugin was installed
-    def self.install(name, source, version = nil)
+    #
+    # @param [String] name of the plugin gem to search in the source
+    # @param [String] source the rubygems URL to resolve the gem
+    # @param [Array, String] version (optional) of the gem to install
+    #
+    # @return [String] the path where the plugin was installed
+    def self.install(name, source, version = [">= 0"])
+
       rg_source = Source::Rubygems.new "remotes" => source, :ignore_app_cache => true
       rg_source.remote!
       rg_source.dependency_names << name
@@ -22,7 +36,13 @@ module Bundler
     end
 
 
-    # Installs the plugin from the provided spec and returns the path where the plugin was installed
+    # Installs the plugin from the provided spec and returns the path where the
+    # plugin was installed.
+    #
+    # @param spec to fetch and install
+    # @raise [ArgumentError] if the spec object has no remote set
+    #
+    # @return [String] the path where the plugin was installed
     def self.install_from_spec(spec)
       raise ArgumentError, "Spec #{spec.name} doesn't have remote set" unless spec.remote