[Documentation] Document the new download cache

lib/cocoapods/downloader.rb

@@ -9,6 +9,21 @@ module Pod
     require 'cocoapods/downloader/request'
     require 'cocoapods/downloader/response'
 
+    # Downloads a pod from the given `request` to the given `target` location.
+    #
+    # @return [Response] The download response for this download.
+    #
+    # @param  [Request] request
+    #         the request that describes this pod download.
+    #
+    # @param  [Pathname,Nil] target
+    #         the location to which this pod should be downloaded. If `nil`,
+    #         then the pod will only be cached.
+    #
+    # @param  [Pathname,Nil] cache_path
+    #         the path used to cache pod downloads. If `nil`, then no caching
+    #         will be done.
+    #
     def self.download(
       request,
       target,

lib/cocoapods/downloader/cache.rb

@@ -3,15 +3,30 @@ require 'tmpdir'
 
 module Pod
   module Downloader
+    # The class responsible for managing Pod downloads, transparently caching
+    # them in a cache directory.
+    #
     class Cache
-
+      # @return [Pathname] The root directory where this cache store its
+      #         downloads.
+      #
       attr_reader :root
 
+      # @param  [Pathname,String] root
+      #         see {#root}
+      #
       def initialize(root)
-        @root = root
+        @root = Pathname(root)
         root.mkpath unless root.exist?
       end
 
+      # Downloads the Pod from the given `request`
+      #
+      # @param  [Request] request
+      #         the request to be downloaded
+      #
+      # @return [Response] the response from downloading `request`
+      #
       def download_pod(request)
         cached_pod(request) || uncached_pod(request)
       rescue Informative
@@ -38,6 +53,9 @@ module Pod
         path.sub_ext('.podspec.json')
       end
 
+      # @return [Response] The download response for the given `request` that
+      #         was found in the download cache.
+      #
       def cached_pod(request)
         path = path_for_pod(request)
         spec = request.spec || cached_spec(request)
@@ -45,11 +63,17 @@ module Pod
         Response.new(path, spec, request.params)
       end
 
+      # @return [Specification] The cached specification for the given
+      #         `request`.
+      #
       def cached_spec(request)
         path = path_for_spec(request)
         path.file? && Specification.from_file(path)
       end
 
+      # @return [Response] The download response for the given `request` that
+      #         was not found in the download cache.
+      #
       def uncached_pod(request)
         in_tmpdir do |target|
           result = Response.new
@@ -77,6 +101,19 @@ module Pod
         end
       end
 
+      # Downloads a pod with the given `name` and `params` to `target`.
+      #
+      # @param  [String] name
+      #
+      # @param  [Pathname] target
+      #
+      # @param  [Hash<Symbol,String>] params
+      #
+      # @param  [Boolean] head
+      #
+      # @return [Hash] The checkout options required to re-download this exact
+      #         same source.
+      #
       def download(name, target, params, head)
         downloader = Downloader.for_target(target, params)
         if head
@@ -97,6 +134,11 @@ module Pod
         end
       end
 
+      # Performs the given block inside a temporary directory,
+      # which is removed at the end of the block's scope.
+      #
+      # @return [Object] The return value of the given block
+      #
       def in_tmpdir(&blk)
         tmpdir = Pathname(Dir.mktmpdir)
         blk.call(tmpdir)
@@ -104,6 +146,17 @@ module Pod
         FileUtils.remove_entry(tmpdir) if tmpdir.exist?
       end
 
+      # Copies the `source` directory to `destination`, cleaning the directory
+      # of any files unused by `spec`.
+      #
+      # @param  [Pathname] source
+      #
+      # @param  [Pathname] destination
+      #
+      # @param  [Specification] spec
+      #
+      # @return [Void]
+      #
       def copy_and_clean(source, destination, spec)
         specs_by_platform = {}
         spec.available_platforms.each do |platform|
@@ -114,6 +167,16 @@ module Pod
         Sandbox::PodDirCleaner.new(destination, specs_by_platform).clean!
       end
 
+      # Writes the given `spec` to the given `path`.
+      #
+      # @param  [Specification] spec
+      #         the specification to be written.
+      #
+      # @param  [Pathname] path
+      #         the path the specification is to be written to.
+      #
+      # @return [Void]
+      #
       def write_spec(spec, path)
         FileUtils.mkdir_p path.dirname
         path.open('w') { |f| f.write spec.to_pretty_json }

lib/cocoapods/downloader/request.rb

 module Pod
   module Downloader
+    # This class represents a download request for a given Pod.
+    #
     class Request
+      # @return [Specification,Nil] The specification for the pod whose download
+      #         is being requested.
+      #
+      attr_reader :spec
+
+      # @return [Boolean] Whether this download request is for a released pod.
+      #
       attr_reader :released_pod
       alias_method :released_pod?, :released_pod
 
-      attr_reader :spec
+      # @return [String] The name of the pod whose dowload is being requested.
+      #
+      attr_reader :name
 
+      # @return [Hash<Symbol, String>] The download parameters for this request.
+      #
+      attr_reader :params
+
+      # @return [Boolean] Whether the download request is for a head download.
+      #
       attr_reader :head
       alias_method :head?, :head
 
-      attr_reader :params
-
-      attr_reader :name
 
+      # @param  [Specification,Nil] spec
+      #         see {#spec}
+      #
+      # @param  [Boolean] released
+      #         see {#released_pod}
+      #
+      # @param  [String,Nil] name
+      #         see {#name}
+      #
+      # @param  [Hash<Symbol,String>,Nil] params
+      #         see {#params}
+      #
+      # @param  [Boolean] head
+      #         see {#head}
+      #
       def initialize(spec: nil, released: false, name: nil, params: false, head: false)
         @released_pod = released
         @spec = spec
@@ -23,6 +52,15 @@ module Pod
         validate!
       end
 
+      # @param  [String] name
+      #         the name of the pod being downloaded.
+      #
+      # @param  [Hash<#to_s, #to_s>] params
+      #         the download parameters of the pod being downloaded.
+      #
+      # @return [String] The slug used to store the files resulting from this
+      #         download request.
+      #
       def slug(name: self.name, params: self.params)
         if released_pod?
           checksum = spec.checksum &&  '-' << spec.checksum.limit(5)
@@ -35,6 +73,10 @@ module Pod
 
       private
 
+      # Validates that the given request is well-formed.
+      #
+      # @return [Void]
+      #
       def validate!
         raise ArgumentError, 'Requires a name' unless name
         raise ArgumentError, 'Requires a version if released' if released_pod? && !spec.version

lib/cocoapods/downloader/response.rb

 module Pod
   module Downloader
+    # A response to a download request.
+    #
+    # @attr [Pathname] location
+    #       the location where this downloaded pod is stored on disk.
+    #
+    # @attr [Specification] spec
+    #       the specification that describes this downloaded pod.
+    #
+    # @attr [Hash<Symbol, String>] checkout_options
+    #       the downloader parameters necessary to recreate this exact download.
+    #
     Response = Struct.new(:location, :spec, :checkout_options)
   end
 end