Merge 55005634-public-API-check to master

Glyn Normington · Glyn Normington · commit 6bd66f338578 · 2013-08-15T11:15:23.000+01:00
[Completes #55005634]
diff --git a/Rakefile b/Rakefile
@@ -17,13 +17,27 @@ require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new
 
 require 'yard'
-YARD::Rake::YardocTask.new
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--no-stats']
+end
 
 require 'rubocop/rake_task'
 Rubocop::RakeTask.new
 
+require 'open3'
+task :check_api_doc do
+  puts "\nChecking API documentation..."
+  output = Open3.capture3("yard stats --list-undoc")[0]
+  if output !~ /100.00% documented/
+  	puts "\nFailed due to undocumented public API:\n\n#{output}"
+  	exit 1
+  else
+  	puts "\n#{output}\n"
+  end
+end
+
 require 'rake/clean'
 CLEAN.include %w(.yardoc coverage)
 CLOBBER.include %w(doc pkg)
 
-task :default => [ :rubocop, :yard, :spec ]
+task :default => [ :rubocop, :check_api_doc, :yard, :spec ]
diff --git a/lib/java_buildpack/diagnostics/common.rb b/lib/java_buildpack/diagnostics/common.rb
@@ -24,10 +24,18 @@ module JavaBuildpack::Diagnostics
   # The name of the buildpack diagnostic log file.
   LOG_FILE_NAME = 'buildpack.log'.freeze
 
+  # Returns the full path of the buildpack diagnostics directory.
+  #
+  # @param [String] app_dir the application root directory
+  # @return [String] the full path of the buildpack diagnostics directory
   def self.get_diagnostic_directory(app_dir)
     File.join(app_dir, DIAGNOSTICS_DIRECTORY)
   end
 
+  # Returns the full path of the buildpack log file.
+  #
+  # @param [String] app_dir the application root directory
+  # @return [String] the full path of the buildpack log file
   def self.get_buildpack_log(app_dir)
     File.join(get_diagnostic_directory(app_dir), LOG_FILE_NAME)
   end
diff --git a/lib/java_buildpack/diagnostics/logger_factory.rb b/lib/java_buildpack/diagnostics/logger_factory.rb
@@ -23,6 +23,7 @@
 
 module JavaBuildpack::Diagnostics
 
+  # Factory for the buildpack diagnostic logger.
   class LoggerFactory
     # Create a Logger for the given application directory.
     #
@@ -116,18 +117,25 @@ def self.close
       end
     end
 
+    # A +Logger+ destination which delegates to multiple underlying destinations.
     class LogSplitter
+      # Initializes a +LogSplitter+ with a given array of destinations.
+      # @param [Array] destinations an array of destinations
       def initialize(*destinations)
         @destinations = destinations
       end
 
+      # Writes to the underlying destinations.
+      #
+      # @param [Array] args the arguments for the delegated call
       def write(*args)
         @destinations.each do |destination|
           destination.write(*args)
           destination.flush
         end
       end
 
+      # Closes the underlying destinations.
       def close
         @destinations.each do |destination|
           destination.close
@@ -136,11 +144,19 @@ def close
 
     end
 
+    # A subclass of the standard +Logger+ which determines the caller from the stack.
     class Logger < ::Logger
+      # Initializes a Logger.
+      # @param [Object] log_dev the destination 'device' to log to
       def initialize(log_dev)
         super
       end
 
+      # Logs a message with a given severity.
+      #
+      # @param [String] severity the severity of the log message
+      # @param [Object, nil] message the message to be logged
+      # @param [String, nil] progname the name of the program logging the message
       def add(severity, message = nil, progname = nil, &block)
 
         if message || block_given?
@@ -158,6 +174,7 @@ def add(severity, message = nil, progname = nil, &block)
         super(severity, message_text, program_name, &block)
       end
 
+      # Closes the logger.
       def close
         warn(caller[0]) { 'logger is being closed' }
         super
diff --git a/lib/java_buildpack/repository/configured_item.rb b/lib/java_buildpack/repository/configured_item.rb
@@ -29,8 +29,8 @@ class ConfiguredItem
     # @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
+    # @return [JavaBuildpack::Util::TokenizedVersion] the chosen version of the file
     def self.find_item(configuration, &version_validator)
       repository_root = ConfiguredItem.repository_root(configuration)
       version = ConfiguredItem.version(configuration)
diff --git a/lib/java_buildpack/util/download.rb b/lib/java_buildpack/util/download.rb
@@ -20,6 +20,13 @@
 
 module JavaBuildpack::Util
 
+  # Downloads a given item using the application cache.
+  #
+  # @param [JavaBuildpack::Util::TokenizedVersion] version the version of the item
+  # @param [String] uri the URI of the item
+  # @param [String] description a description of the item
+  # @param [String] jar_name the filename of the item
+  # @param [String] target_directory the path of the directory into which to download the item
   def self.download(version, uri, description, jar_name, target_directory)
 
     download_start_time = Time.now
