Doc update, minor improvements

Rakefile

@@ -42,7 +42,7 @@ class ConcurrentRubyJavaExtensionTask < Rake::JavaExtensionTask
     unless jruby_cpath
       jruby_home = ENV['JRUBY_HOME']
       if jruby_home
-        candidate = File.join(jruby_home, 'lib', 'jruby.jar')
+        candidate   = File.join(jruby_home, 'lib', 'jruby.jar')
         jruby_cpath = candidate if File.exist? candidate
       end
     end

lib-edge/concurrent/edge/cancellation.rb

@@ -11,10 +11,10 @@ module Concurrent
   #   # stops iterating when cancelled
   # end
 
-  # Provides cooperative cancellation.
+  # The Cancellation abstraction provides cooperative cancellation.
   #
-  # The available `Thread#raise` of `Thread#kill` are very dangerous
-  # (see linked the blog posts bellow).
+  # The standard methods `Thread#raise` of `Thread#kill` available in Ruby
+  # are very dangerous (see linked the blog posts bellow).
   # Therefore concurrent-ruby provides an alternative.
   # * <https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/>
   # * <http://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/>

lib-edge/concurrent/edge/throttle.rb

@@ -5,6 +5,14 @@ module Concurrent
   # When there is no available capacity the current thread may either be blocked or
   # an event is returned which will be resolved when capacity becomes available.
   #
+  # The more common usage of the Throttle is with a proxy executor
+  # `a_throttle.on(Concurrent.global_io_executor)`.
+  # Anything executed on the proxy executor will be throttled and
+  # execute on the given executor. There can be more than one proxy executors.
+  # All abstractions which execute tasks have option to specify executor,
+  # therefore the proxy executor can be injected to any abstraction
+  # throttling its concurrency level.
+  #
   # {include:file:docs-source/throttle.out.md}
   #
   # @!macro warn.edge

spec/spec_helper.rb

@@ -13,7 +13,6 @@ if ENV['COVERAGE']
 
   SimpleCov.start do
     project_name 'concurrent-ruby'
-    add_filter '/build-tests/'
     add_filter '/examples/'
     add_filter '/spec/'
   end

spec/support/example_group_extensions.rb

@@ -30,11 +30,11 @@ module Concurrent
       Concurrent.monotonic_time - start_time
     end
 
-    def in_thread(*args, &block)
+    def in_thread(*arguments, &block)
       @created_threads ||= Queue.new
-      new_thread       = Thread.new(*args) do |*args, &b|
+      new_thread       = Thread.new(*arguments) do |*args, &b|
         Thread.abort_on_exception = true
-        block.call *args, &b
+        block.call(*args, &b)
       end
       @created_threads.push new_thread
       new_thread