Updated the document

docs/extending-application.md

@@ -38,8 +38,11 @@ A helper type (`JavaBuildpack::Component::Services`) that enables querying of th
 # +filter+ matches exactly one service, +false+ otherwise.
 #
 # @param [Regexp, String] filter a +RegExp+ or +String+ to match against the name, label, and tags of the services
-# @return [Boolean] +true+ if the +filter+ matches exactly one service, +false+ otherwise.
-def one_service?(filter)
+# @param [String] required_credentials an optional list of keys or groups of keys, where at least one key from the
+#                                      group, must exist in the credentials payload of the candidate service
+# @return [Boolean] +true+ if the +filter+ matches exactly one service with the required credentials, +false+
+#                   otherwise.
+def one_service?(filter, *required_credentials)
 
 # Compares the name, label, and tags of each service to the given +filter+.  The method returns the first service
 # that the +filter+ matches.  If no service matches, returns +nil+

docs/extending-base_component.md

@@ -48,7 +48,7 @@ def release
 # @param [String] uri
 # @param [String] name an optional name for the download.  Defaults to +@component_name+.
 # @return [Void]
-def download(version, uri, name = @component_name, &block)
+def download(version, uri, name = @component_name)
 
 # Downloads a given JAR file and stores it.
 #
@@ -57,6 +57,7 @@ def download(version, uri, name = @component_name, &block)
 # @param [String] jar_name the name to save the jar as
 # @param [Pathname] target_directory the directory to store the JAR file in.  Defaults to the component's sandbox.
 # @param [String] name an optional name for the download.  Defaults to +@component_name+.
+# @return [Void]
 def download_jar(version, uri, jar_name, target_directory = @droplet.sandbox, name = @component_name)
 
 # Downloads a given TAR file and expands it.
@@ -65,18 +66,21 @@ def download_jar(version, uri, jar_name, target_directory = @droplet.sandbox, na
 # @param [String] uri the uri of the download
 # @param [Pathname] target_directory the directory to expand the TAR file to.  Defaults to the component's sandbox.
 # @param [String] name an optional name for the download and expansion.  Defaults to +@component_name+.
+# @return [Void]
 def download_tar(version, uri, target_directory = @droplet.sandbox, name = @component_name)
 
 # Downloads a given ZIP file and expands it.
 #
 # @param [Boolean] strip_top_level whether to strip the top-level directory when expanding. Defaults to +true+.
 # @param [Pathname] target_directory the directory to expand the ZIP file to.  Defaults to the component's sandbox.
 # @param [String] name an optional name for the download.  Defaults to +@component_name+.
+# @return [Void]
 def download_zip(version, uri, strip_top_level = true, target_directory = @droplet.sandbox, name = @component_name)
 
 # Wrap the execution of a block with timing information
 #
 # @param [String] caption the caption to print when timing starts
+# @return [Void]
 def with_timing(caption)
 ```
 

docs/extending-caches.md

@@ -51,20 +51,21 @@ Caching can be configured by modifying the [`config/cache.yml`][] file in the bu
 The [`DownloadCache`][] is the most generic of the two caches.  It allows you to create a cache that persists files any that write access is available.  The constructor signature looks the following:
 
 ```ruby
-# Creates an instance of the cache that is backed by the filesystem rooted at +cache_root+
+# Creates an instance of the cache that is backed by a number of filesystem locations.  The first argument
+# (+mutable_cache_root+) is the only location that downloaded files will be stored in.
 #
-# @param [String] cache_root the filesystem root for downloaded files to be cached in
-def initialize(cache_root = Dir.tmpdir)
+# @param [Pathname] mutable_cache_root the filesystem location in which find cached files in.  This will also be
+#                                      the location that all downloaded files are written to.
+# @param [Pathname] immutable_cache_roots other filesystem locations to find cached files in.  No files will be
+#                                         written to these locations.
+def initialize(mutable_cache_root = Pathname.new(Dir.tmpdir), *immutable_cache_roots)
 ```
 
 ## `JavaBuildpack::Util::Cache::ApplicationCache`
 The [`ApplicationCache`][] is a cache that persists files into the application cache passed to the `compile` script.  It examines `ARGV[1]` for the cache location and configures itself accordingly.
 
 ```ruby
-# Creates an instance that is configured to use the application cache.  The application cache location is defined by
-# the second argument (<tt>ARGV[1]</tt>) to the +compile+ script.
-#
-# @raise if the second argument (<tt>ARGV[1]</tt>) to the +compile+ script is +nil+
+# Creates an instance of the cache that is backed by the the application cache
 def initialize
 ```
 

docs/extending-droplet.md

@@ -32,7 +32,8 @@ attr_reader :sandbox
 
 # Copy resources from a components resources directory to a directory
 #
-# @param [Pathname] target_directory the directory to copy to.  Default to a component's +sandbox+
+# @param [Pathname] target_directory the directory to copy to.  Defaults to the component's +sandbox+.
+# @return [Void]
 def copy_resources(target_directory = @sandbox)
 ```
 
@@ -48,6 +49,7 @@ def as_classpath
 # Symlink the contents of the collection to a destination directory.
 #
 # @param [Pathname] destination the destination to link to
+# @return [Void]
 def link_to(destination)
 ```
 
@@ -58,17 +60,18 @@ The id of the component, as determined by the buildpack.  This is used in variou
 One of two helper types (`JavaBuildpack::Component::ImmutableJavaHome`, `JavaBuildpack::Component::MutableJavaHome`) that enables the mutation and retrieval of the droplet's `JAVA_HOME`.  Components that are JREs will be given the `MutableJavaHome` in order to set the value.  All other components will be given the `ImmutableJavaHome` in order to retrieve the value.
 
 ```ruby
-# Returns the path of +JAVA_HOME+ as an environment variable formatted as +JAVA_HOME="$PWD/<value>"+
+# Returns the path of +JAVA_HOME+ as an environment variable formatted as +JAVA_HOME=$PWD/<value>+
 #
 # @return [String] the path of +JAVA_HOME+ as an environment variable
 def as_env_var
 
 # Execute a block with the +JAVA_HOME+ environment variable set
 #
 # @yield yields to block with the +JAVA_HOME+ environment variable set
+# @return [Object] the returned value of the block
 def do_with
 
-# @return [String] the root of the droplet's +JAVA_HOME+
+# @return [String] the root of the droplet's +JAVA_HOME+ formatted as +$PWD/<value>+
 def root
 
 # Sets the root of the droplet's +JAVA_HOME+

docs/extending-modular_component.md

@@ -10,11 +10,12 @@ This base class is recommended for use by any component that is sufficiently com
 #                        components are expected to return the command required to run the application.
 def command
 
-# The modules that make up this component
+# The sub_components that make up this component
 #
 # @param [Hash] context the context of the component
-# @return [Array<BaseComponent>] a collection of +BaseComponent+s that make up the modules of this component
-def modules(context)
+# @return [Array<BaseComponent>] a collection of +BaseComponent+s that make up the sub_components of this
+#                                component
+def sub_components(_context)
 
 # Whether or not this component supports this application
 #

docs/extending-repositories.md

@@ -22,15 +22,17 @@ An example filesystem might look like:
 The main class used when dealing with a repository is [`JavaBuildpack::Repository::ConfiguredItem`][].  It provides a single method that is used to resolve a specific version and its URI.
 
 ```ruby
-# Finds an instance of the file based on the configuration.
+# Finds an instance of the file based on the configuration and wraps any exceptions
+# to identify the component.
 #
+# @param [String] component_name the name of the component
 # @param [Hash] configuration the configuration
 # @option configuration [String] :repository_root the root directory of the repository
 # @option configuration [String] :version the version of the file to resolve
 # @param [Block, nil] version_validator an optional version validation block
-# @return [JavaBuildpack::Util::TokenizedVersion] the chosen version of the file
 # @return [String] the URI of the chosen version of the file
-def find_item(configuration, &version_validator)
+# @return [JavaBuildpack::Util::TokenizedVersion] the chosen version of the file
+def find_item(component_name, configuration)
 ```
 
 Usage of the class might look like the following: