definition.rb in bundler-1.4.0.pre.1

- old
+ new

@@ -6,10 +6,17 @@
     include GemHelpers
 
     attr_reader :dependencies, :platforms, :sources, :ruby_version,
       :locked_deps
 
+    # Given a gemfile and lockfile creates a Bundler definition
+    #
+    # @param gemfile [Pathname] Path to Gemfile
+    # @param lockfile [Pathname,nil] Path to Gemfile.lock
+    # @param unlock [Hash, Boolean, nil] Gems that have been requested
+    #   to be updated or true if all gems should be updated
+    # @return [Bundler::Definition]
     def self.build(gemfile, lockfile, unlock)
       unlock ||= {}
       gemfile = Pathname.new(gemfile).expand_path
 
       unless gemfile.file?
@@ -17,22 +24,28 @@
       end
 
       Dsl.evaluate(gemfile, lockfile, unlock)
     end
 
-=begin
-    How does the new system work?
-    ===
-    * Load information from Gemfile and Lockfile
-    * Invalidate stale locked specs
-      * All specs from stale source are stale
-      * All specs that are reachable only through a stale
-        dependency are stale.
-    * If all fresh dependencies are satisfied by the locked
-      specs, then we can try to resolve locally.
-=end
 
+    #
+    # How does the new system work?
+    #
+    # * Load information from Gemfile and Lockfile
+    # * Invalidate stale locked specs
+    #  * All specs from stale source are stale
+    #  * All specs that are reachable only through a stale
+    #    dependency are stale.
+    # * If all fresh dependencies are satisfied by the locked
+    #  specs, then we can try to resolve locally.
+    #
+    # @param lockfile [Pathname] Path to Gemfile.lock
+    # @param dependencies [Array(Bundler::Dependency)] array of dependencies from Gemfile
+    # @param sources [Array(Bundler::Source::Rubygems)]
+    # @param unlock [Hash, Boolean, nil] Gems that have been requested
+    #   to be updated or true if all gems should be updated
+    # @param ruby_version [Bundler::RubyVersion, nil] Requested Ruby Version
     def initialize(lockfile, dependencies, sources, unlock, ruby_version = nil)
       @unlocking = unlock == true || !unlock.empty?
 
       @dependencies, @sources, @unlock = dependencies, sources, unlock
       @remote            = false
@@ -107,10 +120,16 @@
       @remote = true
       @sources.each { |s| s.remote! }
       specs
     end
 
+    # For given dependency list returns a SpecSet with Gemspec of all the required
+    # dependencies.
+    #  1. The method first resolves the dependencies specified in Gemfile
+    #  2. After that it tries and fetches gemspec of resolved dependencies
+    #
+    # @return [Bundler::SpecSet]
     def specs
       @specs ||= begin
         specs = resolve.materialize(requested_dependencies)
 
         unless specs["bundler"].any?
@@ -157,9 +176,14 @@
       deps = dependencies.select { |d| (d.groups & groups).any? }
       deps.delete_if { |d| !d.should_include? }
       specs.for(expand_dependencies(deps))
     end
 
+    # Resolve all the dependencies specified in Gemfile. It ensures that
+    # dependencies that have been already resolved via locked file and are fresh
+    # are reused when resolving dependencies
+    #
+    # @return [SpecSet] resolved dependencies
     def resolve
       @resolve ||= begin
         if Bundler.settings[:frozen] || (!@unlocking && nothing_changed?)
           @locked_specs
         else