bean_counter 0.0.3 → 0.0.4

data/lib/bean_counter/strategy.rb

@@ -25,26 +25,25 @@ class BeanCounter::Strategy
   @@strategies = {}
 
 
-  # Maintain an index of classes known to subclass Strategy.
+  # Used to maintain an index of classes known to subclass Strategy.
   def self.inherited(subclass)
     identifier = subclass.name || subclass.to_s[8, subclass.to_s.length - 9]
     @@strategies[identifier.to_sym] = subclass
   end
 
 
-  # :call-seq:
-  #   known_strategy?(strategy_identifier) => Boolean
-  #
-  # Determines if the provided +strategy_identifer+ corresponds to a known
-  # subclass of strategy. The provided +strategy_identifer+ can be a class
-  # or any object that responds to :to_sym. Classes are compared directly.
+  # Determines if the provided `strategy_identifer` corresponds to a known
+  # subclass of strategy. The provided `strategy_identifer` can be a class
+  # or any object that implements :to_sym. Classes are compared directly.
   # For non-class objects that respond to :to_sym, the symbolized form
-  # of +strategy_identifer+ is used as a key to attempt to retrieve a strategy
+  # of `strategy_identifer` is used as a key to attempt to retrieve a strategy
   # from the strategies Hash.
   #
-  # Returns true if +strategy_identifier+ isa known strategy or maps to a known
-  # strategy. Otherwise, false is returned.
-  #
+  # @param strategy_identifier [Object] A class or any Object that implements
+  #   :to_sym
+  # @return [Boolean] Returns true if `strategy_identifier` is a known
+  #   strategy or maps to a known strategy. Otherwise, false is returned.
+  # @example
   #   BeanCounter::Strategy.known_strategy?(Object)
   #     #=> false
   #
@@ -59,16 +58,18 @@ class BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   materialize_strategy(strategy_identifier) => subclass of Strategy
-  #
-  # Materialize the provided +strategy_identifier+ into a subclass of Strategy.
-  # If +strategy_identifer+ is already a subclass of Strategy,
-  # +strategy_identifier+ is returned. Otherwise, +strategy_identifer+ is
+  # Materialize the provided `strategy_identifier` into a subclass of Strategy.
+  # If `strategy_identifer` is already a subclass of Strategy,
+  # `strategy_identifier` is returned. Otherwise, `strategy_identifer` is
   # converted into a Symbol and is used as a key to retrieve a strategy from
-  # the known subclasses of Strategy. If +strategy_identifier does not map to
+  # the known subclasses of Strategy. If `strategy_identifier` does not map to
   # a known subclass of Strategy, an ArgumentError is raised.
   #
+  # @param strategy_identifier [Object] A class or any Object that implements
+  #   :to_sym
+  # @return [BeanCounter::Strategy] The strategy the given `strategy_identifier`
+  #   was materialized into
+  # @example
   #   BeanCounter::Strategy.materialize_strategy(:'BeanCounter::Strategy::StalkClimberStrategy')
   #     #=> BeanCounter::Strategy::StalkClimberStrategy
   def self.materialize_strategy(strategy_identifier)
@@ -82,27 +83,30 @@ class BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   strategies() => Hash
-  #
   # Returns a list of known classes that inherit from BeanCounter::Strategy.
   # Typically this list represents the strategies available for interacting
   # with beanstalkd.
+  #
+  # @return [Array<BeanCounter::Strategy>] A list of classes known to inherit
+  #   from BeanCounter::Strategy.
   def self.strategies
     return @@strategies.dup
   end
 
 
-  # :call-seq:
-  #   collect_new_jobs { block } => Array[Strategy Job]
-  #
   # Provide a means of collecting jobs enqueued during the execution of the
-  # provided +block+. Returns an Array of Jobs as implemented by the Strategy.
+  # provided `block`. Returns an Array of Jobs as implemented by the Strategy.
   #
   # Used internally to reduce the set of jobs that must be examined to evaluate
   # the truth of an assertion to only those enqueued during the evaluation of
-  # the given +block+.
-  #
+  # the given `block`.
+  #
+  # @abstract Subclasses must override to implement
+  # @yield Nothing yielded to provided block
+  # @yieldreturn [void] No specific value is expected from provided block
+  # @return [Array<Strategy::Job>] Returns an Array of Jobs as implemented by
+  #   the Strategy.
+  # @example
   #   new_jobs = strategy.collect_new_jobs do
   #     ...
   #   end
@@ -112,45 +116,54 @@ class BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   delete_job(job) => Boolean
-  #
   # Provide a means for deleting a job specific to the job interface used by
-  # the strategy. Should return true if the job was deleted successfully or
-  # no longer exists and false if the job could not be deleted.
+  #   the strategy.
+  # Should return true if the job was deleted successfully or no longer exists
+  # and false if the job could not be deleted.
   #
   # Used internally to delete a job, allowing the beanstalkd pool to be reset.
   #
-  # strategy.delete_job(job)
-  #   #=> true
+  # @abstract Subclasses must override to implement
+  # @param job [Strategy::Job] The job to be deleted.
+  # @return [Boolean] True if the job was deleted successfully or no longer
+  #   exists, false if the job could not be deleted.
+  # @example
+  #   strategy.delete_job(job)
+  #     #=> true
   def delete_job
     raise NotImplementedError
   end
 
 
-  # :call-seq:
-  #   job_matches?(job, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
-  #
-  # Returns a boolean indicating whether or not the provided +job+ matches the
-  # given Hash of +options. Each _key_ in +options+ is a String or a Symbol that
-  # identifies an attribute of +job+ that the corresponding _value_ should be
-  # compared against. True is returned if every _value_ in +options+ evaluates to
-  # true when compared to the attribute of +job+ identified by the corresponding
-  # _key_. False is returned if any of the comparisons evaluates to false.
+  # Returns a boolean indicating whether or not the provided `job` matches the
+  # given Hash of `options`. Each `key` in `options` is a String or a Symbol that
+  # identifies an attribute of `job` that the corresponding `value` should be
+  # compared against. True is returned if every `value` in `options` evaluates to
+  # true when compared to the attribute of `job` identified by the corresponding
+  # `key`. False is returned if any of the comparisons evaluates to false.
   #
   # If no options are given, returns true for any job that exists at the time of
   # evaluation.
   #
-  # Each attribute comparison is performed using the triple equal (===)
-  # operator/method of _value_ with the attribute of +job+ identified by _key_
+  # Each attribute comparison is performed using the triple-equal (===)
+  # operator/method of `value` with the attribute of `job` identified by `key`
   # passed into the method. Use of === allows for more complex comparisons
   # using Procs, Ranges, Regexps, etc.
   #
-  # Consult MATCHABLE_JOB_ATTRIBUTES for a list of which attributes of +job+
+  # Consult {MATCHABLE_JOB_ATTRIBUTES} for a list of which attributes of `job`
   # can be matched against.
   #
   # Used internally to evaluate if a job matches an assertion.
   #
+  # @abstract Subclasses must override to implement
+  # @param job [Strategy::Job] The job to evaluate for a match.
+  # @param options [Hash{Symbol, String => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options used to evaluate match.
+  # @return [Boolean] True if every value of the `options` Hash evaluates to
+  #   true when comared to the attribute of `job` identified by the
+  #   corresponding key. False is returned if any of the comparisons evaluates
+  #   to false.
+  # @example
   #   strategy.job_matches?(reserved_job, :state => 'reserved')
   #     #=> true
   #
@@ -164,65 +177,75 @@ class BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   jobs() => Enumerator
-  #
-  # Returns an Enumerator providing a means to enumerate all jobs in the beanstalkd
-  # pool.
+  # Returns an Enumerator providing a means to enumerate all jobs in the
+  #   Beanstalkd pool.
   #
   # Used internally to enumerate all jobs to find jobs matching an assertion.
+  #
+  # @abstract Subclasses must override to implement
+  # @return [Enumerator<Strategy::Job>] An Enumerator of all jobs in the
+  #   Beanstalkd pool
   def jobs
     raise NotImplementedError
   end
 
 
-  # :call-seq:
-  #   pretty_print_job(job) => String
-  #
-  # Returns a String representation of +job+ in a pretty, human readable
-  # format.
+  # Returns a String representation of `job` in a pretty, human-readable
+  #   format.
   #
   # Used internally to print a job when an assertion fails.
+  #
+  # @abstract Subclasses must override to implement
+  # @param job [Strategy::Job] The job to represent in a pretty, human-readable
+  #   format
+  # @return [String] `job` in a more human-readable format
   def pretty_print_job
     raise NotImplementedError
   end
 
 
-  # :call-seq:
-  #   pretty_print_tube(tube) => String
-  #
-  # Returns a String representation of the tube in a pretty, human readable
-  # format. Used internally to print a tube when an assertion fails.
+  # Returns a String representation of the tube in a pretty, human-readable
+  #   format.
   #
   # Used internally to print a tube when an assertion fails.
+  #
+  # @abstract Subclasses must override to implement
+  # @param tube [Strategy::Tube] The tube to represent in a pretty, human-readable
+  #   format
+  # @return [String] `tube` in a more human-readable format.
   def pretty_print_tube
     raise NotImplementedError
   end
 
-
-  # :call-seq:
-  #   tube_matches?(tube, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
-  #
-  # Returns a boolean indicating whether or not the provided +tube+ matches the
-  # given Hash of +options. Each _key_ in +options+ is a String or a Symbol that
-  # identifies an attribute of +tube+ that the corresponding _value_ should be
-  # compared against. True is returned if every _value_ in +options+ evaluates to
-  # true when compared to the attribute of +tube+ identified by the corresponding
-  # _key_. False is returned if any of the comparisons evaluates to false.
+  # Returns a boolean indicating whether or not the provided `tube` matches the
+  # given Hash of `options`. Each `key` in `options` is a String or a Symbol that
+  # identifies an attribute of `tube` that the corresponding `value` should be
+  # compared against. True is returned if every `value` in `options` evaluates to
+  # true when compared to the attribute of `tube` identified by the corresponding
+  # `key`. False is returned if any of the comparisons evaluates to false.
   #
   # If no options are given, returns true for any tube that exists at the time of
   # evaluation.
   #
-  # Each attribute comparison is performed using the triple equal (===)
-  # operator/method of _value_ with the attribute of +job+ identified by _key_
+  # Each attribute comparison is performed using the triple-equal (===)
+  # operator/method of `value` with the attribute of `job` identified by `key`
   # passed into the method. Use of === allows for more complex comparisons using
   # Procs, Ranges, Regexps, etc.
   #
-  # Consult MATCHABLE_TUBE_ATTRIBUTES for a list of which attributes of +tube+
+  # Consult {MATCHABLE_TUBE_ATTRIBUTES} for a list of which attributes of `tube`
   # can be matched against.
   #
   # Used internally to evaluate if a tube matches an assertion.
   #
+  # @abstract Subclasses must override to implement
+  # @param tube [Strategy::Tube] The tube to evaluate for a match.
+  # @param options [Hash{Symbol, String => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options used to evaluate match.
+  # @return [Boolean] True if every value of the `options` Hash evaluates to
+  #   true when comared to the attribute of `tube` identified by the
+  #   corresponding key. False is returned if any of the comparisons evaluates
+  #   to false.
+  # @example
   #   strategy.tube_matches?(paused_tube, :state => 'paused')
   #     #=> true
   #
@@ -236,13 +259,14 @@ class BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   tubes() => Enumerator
-  #
   # Returns an Enumerator providing a means to enumerate all tubes in the beanstalkd
   # pool.
   #
   # Used internally to enumerate all tubes to find tubes matching an assertion.
+  #
+  # @abstract Subclasses must override to implement
+  # @return [Enumerator<Strategy::Tube>] An Enumerator of all tubes in the
+  #   Beanstalkd pool
   def tubes
     raise NotImplementedError
   end

data/lib/bean_counter/test_assertions.rb

@@ -1,32 +1,41 @@
 module BeanCounter::TestAssertions
 
-  # :call-seq:
-  #   assert_enqueued(options = {Symbol,String => Numeric,Proc,Range,Regexp,String})
-  #
   # Asserts that some number of jobs are enqueued that match the given Hash of
-  # +options+. If no +options+ are given, asserts that at least one job exists.
+  # `options`. If no `options` are given, asserts that at least one job exists.
   #
-  # Each _key_ in +options+ is a String or a Symbol that identifies an attribute
-  # of a job that the corresponding _value_ should be compared against. All attribute
-  # comparisons are performed using the triple equal (===) operator/method of
-  # the given _value_.
+  # Each `key` in `options` is a String or a Symbol that identifies an attribute
+  # of a job that the corresponding `value` should be compared against. All attribute
+  # comparisons are performed using the triple-equal (===) operator/method of
+  # the given `value`.
   #
-  # +options+ may additionally include a _count_ key of 'count' or :count that
+  # `options` may additionally include a `count` key ('count' or :count) that
   # can be used to assert that a particular number of matching jobs are found.
   #
-  # If no _count_ option is provided, the assertion succeeds if any job is found
-  # that matches all of the +options+ given. If no jobs are found that match the
-  # +options+ given, the assertion fails.
+  # If no `count` option is provided, the assertion succeeds if any job is found
+  # that matches all of the `options` given. If no jobs are found that match the
+  # `options` given, the assertion fails.
   #
-  # If a _count_ option is provided the assertion only succeeds if the triple equal
-  # (===) operator/method of the value of _count_ evaluates to true when given the
+  # If a `count` option is provided the assertion only succeeds if the triple-equal
+  # (===) operator/method of the value of `count` evaluates to true when given the
   # total number of matching jobs. Otherwise the assertion fails. The use of ===
   # allows for more advanced comparisons using Procs, Ranges, Regexps, etc.
   #
-  # See Strategy#job_matches? and/or the #job_matches? method of the strategy
-  # in use for more detailed information on how it is determined whether or not
-  # a job matches the given +options+.
-  #
+  # See {BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES} for a list of what
+  # attributes can be used when matching.
+  #
+  # See {BeanCounter::Strategy#job_matches?} and/or the #job_matches? method of
+  # the strategy in use for more detailed information on how it is determined
+  # whether or not a job matches the given `options`.
+  #
+  # @see BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::Strategy#job_matches?
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match assertion.
+  # @option options [Numeric, Range] :count (nil) A particular number of matching
+  #   jobs expected
+  # @return [true] if the assertion succeeds
+  # @example
   #   assert_enqueued
   #
   #   assert_enqueued(:body => /test/, :count => 5)
@@ -37,40 +46,51 @@ module BeanCounter::TestAssertions
   end
 
 
-  # :call-seq:
-  #   assert_enqueues(options = {Symbol,String => Numeric,Proc,Range,Regexp,String}) { block }
+  # Asserts that the provided `block` enqueues some number of jobs that match
+  # the given Hash of `options`. If no `options` are given, asserts that at
+  # least one job is enqueued during the execution of the `block`.
   #
-  # Asserts that the given +block+ enqueues some number of jobs that match the
-  # given Hash of +options+. If no +options+ are given, asserts that at least
-  # one job is enqueued during the execution of the +block+.
-  #
-  # Unlike #assert_enqueued, which will evaluate all jobs in the beanstalkd pool,
+  # Unlike {#assert_enqueued}, which will evaluate all jobs in the Beanstalkd pool,
   # this method will only evaluate jobs that were enqueued during the
-  # execution of the given +block+. This can be useful for performance and for
+  # execution of the given `block`. This can be useful for performance and for
   # making assertions that could return false positives if all jobs were
   # evaluated.
   #
-  # Each _key_ in +options+ is a String or a Symbol that identifies an attribute
-  # of a job that the corresponding _value_ should be compared against. All attribute
-  # comparisons are performed using the triple equal (===) operator/method of
-  # the given _value_.
+  # Each `key` in `options` is a String or a Symbol that identifies an attribute
+  # of a job that the corresponding `value` should be compared against. All attribute
+  # comparisons are performed using the triple-equal (===) operator/method of
+  # the given `value`.
   #
-  # +options+ may additionally include a _count_ key of 'count' or :count that
+  # `options` may additionally include a `count` key ('count' or :count) that
   # can be used to assert that a particular number of matching jobs are found.
   #
-  # If no _count_ option is provided, the assertion succeeds if any job is found
-  # that matches all of the +options+ given. If no jobs are found that match the
-  # +options+ given, the assertion fails.
+  # If no `count` option is provided, the assertion succeeds if any job is found
+  # that matches all of the `options` given. If no jobs are found that match the
+  # `options` given, the assertion fails.
   #
-  # If a _count_ option is provided the assertion only succeeds if the triple equal
-  # (===) operator/method of the value of _count_ evaluates to true when given the
+  # If a `count` option is provided the assertion only succeeds if the triple-equal
+  # (===) operator/method of the value of `count` evaluates to true when given the
   # total number of matching jobs. Otherwise the assertion fails. The use of ===
   # allows for more advanced comparisons using Procs, Ranges, Regexps, etc.
   #
-  # See Strategy#job_matches? and/or the #job_matches? method of the strategy
-  # in use for more detailed information on how it is determined whether or not
-  # a job matches the given +options+.
-  #
+  # See {BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES} for a list of what
+  # attributes can be used when matching.
+  #
+  # See {BeanCounter::Strategy#job_matches?} and/or the #job_matches? method of
+  # the strategy in use for more detailed information on how it is determined
+  # whether or not a job matches the given `options`.
+  #
+  # @see BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::Strategy#job_matches?
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match assertion.
+  # @option options [Numeric, Range] :count (nil) A particular number of matching
+  #   jobs expected
+  # @yield No value is yielded to the provided block.
+  # @raise [ArgumentError] if no block is given.
+  # @return [true] if the assertion succeeds
+  # @example
   #   assert_enqueues(:body => /test/) do
   #     enqueue_some_jobs
   #   end
@@ -81,26 +101,32 @@ module BeanCounter::TestAssertions
   end
 
 
-  # :call-seq:
-  #   assert_tube(options = {Symbol,String => Numeric,Proc,Range,Regexp,String})
-  #
   # Asserts that at least one tube exist that matches the given Hash of
-  # +options+. If no +options+ are given, asserts that at least one tube exists,
+  # `options`. If no `options` are given, asserts that at least one tube exists,
   # which will always succeed.
   #
-  # Each _key_ in +options+ is a String or a Symbol that identifies an attribute
-  # of a tube that the corresponding _value_ should be compared against. All attribute
-  # comparisons are performed using the triple equal (===) operator/method of
-  # the given _value_.
+  # Each `key` in `options` is a String or a Symbol that identifies an attribute
+  # of a tube that the corresponding `value` should be compared against. All attribute
+  # comparisons are performed using the triple-equal (===) operator/method of
+  # the given `value`.
   #
   # The assertion succeeds if any tube exists that matches all of the given
-  # +options+. If no tube exists matching all of the given +options+, the assertion
+  # `options`. If no tube exists matching all of the given `options`, the assertion
   # fails.
   #
-  # See Strategy#tube_matches? and/or the #tube_matches? method of the strategy
-  # in use for more detailed information on how it is determined whether or not
-  # a tube matches the given +options+.
+  # See {BeanCounter::Strategy::MATCHABLE_TUBE_ATTRIBUTES} for a list of those
+  # attributes that can be used when matching.
+  #
+  # See {BeanCounter::Strategy#tube_matches?} and/or the #tube_matches? method of
+  # the strategy in use for more detailed information on how it is determined
+  # whether or not a tube matches the given `options`.
   #
+  # @see BeanCounter::Strategy::MATCHABLE_TUBE_ATTRIBUTES
+  # @see BeanCounter::Strategy#tube_matches?
+  # @param options [Hash{Symbol, String => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match assertion.
+  # @return [true] if the assertion succeeds
+  # @example
   #   assert_tube
   #
   #   assert_tube(:name => /test/)
@@ -111,24 +137,31 @@ module BeanCounter::TestAssertions
   end
 
 
-  # :call-seq:
-  #   refute_enqueued(options = {Symbol,String => Numeric,Proc,Range,Regexp,String})
+  # Asserts that no jobs are enqueued that match the given Hash of `options`.
+  # If no `options` are given, asserts that no jobs exist.
   #
-  # Asserts that no jobs are enqueued that match the given Hash of +options+.
-  # If no +options+ are given, asserts that no jobs exist.
+  # Each `key` in `options` is a String or a Symbol that identifies an attribute
+  # of a job that the corresponding `value` should be compared against. All attribute
+  # comparisons are performed using the triple-equal (===) operator/method of
+  # the given `value`.
   #
-  # Each _key_ in +options+ is a String or a Symbol that identifies an attribute
-  # of a job that the corresponding _value_ should be compared against. All attribute
-  # comparisons are performed using the triple equal (===) operator/method of
-  # the given _value_.
-  #
-  # The refutation succeeds if no jobs are found that match all of the +options+
+  # The refutation succeeds if no jobs are found that match all of the `options`
   # given. If any matching jobs are found, the refutation fails.
   #
-  # See Strategy#job_matches? and/or the #job_matches? method of the strategy
-  # in use for more detailed information on how it is determined whether or not
-  # a job matches the given +options+.
+  # See {BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES} for a list of what
+  # attributes can be used when matching.
+  #
+  # See {BeanCounter::Strategy#job_matches?} and/or the #job_matches? method of
+  # the strategy in use for more detailed information on how it is determined
+  # whether or not a job matches the given `options`.
   #
+  # @see BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::Strategy#job_matches?
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match assertion.
+  # @return [false] if the refutation succeeds
+  # @example
   #   refute_enqueued
   #
   #   refute_enqueued(:body => lambda {|body| body.length > 50})
@@ -139,31 +172,39 @@ module BeanCounter::TestAssertions
   end
 
 
-  # :call-seq:
-  #   refute_enqueues(options = {Symbol,String => Numeric,Proc,Range,Regexp,String}) { block }
+  # Asserts that the given `block` enqueues no jobs that match the given Hash
+  # of `options`. If no `options` are given, asserts that no job are enqueued
+  # by the given `block`.
   #
-  # Asserts that the given +block+ enqueues no jobs that match the given Hash
-  # of +options+. If no +options+ are given, asserts that no job are enqueued
-  # by the given +block+.
-  #
-  # Unlike #refute_enqueued, which will evaluate all jobs in the beanstalkd pool,
+  # Unlike {#refute_enqueued}, which will evaluate all jobs in the beanstalkd pool,
   # this method will only evaluate jobs that were enqueued during the
-  # execution of the given +block+. This can be useful for performance and for
+  # execution of the given `block`. This can be useful for performance and for
   # making assertions that could return false positives if all jobs were
   # evaluated.
   #
-  # Each _key_ in +options+ is a String or a Symbol that identifies an attribute
-  # of a job that the corresponding _value_ should be compared against. All attribute
-  # comparisons are performed using the triple equal (===) operator/method of
-  # the given _value_.
+  # Each `key` in `options` is a String or a Symbol that identifies an attribute
+  # of a job that the corresponding `value` should be compared against. All attribute
+  # comparisons are performed using the triple-equal (===) operator/method of
+  # the given `value`.
   #
-  # The refutation succeeds if no jobs are found that match all of the +options+
+  # The refutation succeeds if no jobs are found that match all of the `options`
   # given. If any matching jobs are found, the refutation fails.
   #
-  # See Strategy#job_matches? and/or the #job_matches? method of the strategy
-  # in use for more detailed information on how it is determined whether or not
-  # a job matches the given +options+.
-  #
+  # See {BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES} for a list of what
+  # attributes can be used when matching.
+  #
+  # See {BeanCounter::Strategy#job_matches?} and/or the #job_matches? method of
+  # the strategy in use for more detailed information on how it is determined
+  # whether or not a job matches the given `options`.
+  #
+  # @see BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::Strategy#job_matches?
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match assertion.
+  # @yield The provided block is given no parameters.
+  # @return [false] if the refutation succeeds
+  # @example
   #   refute_enqueues do
   #     do_some_work_that_should_not_enqueue_any_jobs
   #   end
@@ -174,25 +215,34 @@ module BeanCounter::TestAssertions
   end
 
 
-  # :call-seq:
-  #   refute_tube(options = {Symbol,String => Numeric,Proc,Range,Regexp,String})
-  #
-  # Asserts that no tube exist that matches the given Hash of +options+.
+  # Asserts that no tube exist that matches the given Hash of `options`.
   # If no options are given, asserts that no tubes exist which will always fail.
   #
-  # Each _key_ in +options+ is a String or a Symbol that identifies an attribute
-  # of a tube that the corresponding _value_ should be compared against. All attribute
-  # comparisons are performed using the triple equal (===) operator/method of
-  # the given _value_.
+  # Each `key` in `options` is a String or a Symbol that identifies an attribute
+  # of a tube that the corresponding `value` should be compared against. All attribute
+  # comparisons are performed using the triple-equal (===) operator/method of
+  # the given `value`.
   #
   # The refutation succeeds if no tube exists that matches all of the given
-  # +options+. If any tubes exist that match all of the given +options+, the
+  # `options`. If any tubes exist that match all of the given `options`, the
   # refutation fails.
   #
-  # See Strategy#tube_matches? and/or the #tube_matches? method of the strategy
-  # in use for more detailed information on how it is determined whether or not
-  # a tube matches the given +options+.
+  # See {BeanCounter::Strategy::MATCHABLE_TUBE_ATTRIBUTES} for a list of those
+  # attributes that can be used when matching.
   #
+  # See {BeanCounter::Strategy#tube_matches?} and/or the #tube_matches? method of the strategy
+  # in use for more detailed information on how it is determined whether or not
+  # a tube matches the given `options`.
+  #
+  # @see BeanCounter::Strategy::MATCHABLE_TUBE_ATTRIBUTES
+  # @see BeanCounter::Strategy#job_matches?
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match assertion.
+  # @option options [Numeric, Range] :count (nil) A particular number of matching
+  #   jobs expected
+  # @return [false] if the refutation succeeds
+  # @example
   #   refute_tube
   #     #=> always fails
   #
@@ -206,8 +256,8 @@ module BeanCounter::TestAssertions
   private
 
 
-  # Builds job expectation object, evaluates and makes appropriate assertion
-  # with appropriate failure message
+  # Builds job expectation object, evaluates, and makes appropriate assertion
+  # with appropriate failure message.
   def enqueue_expectation(assertion_method, options, &block)
     message_type = assertion_method == :assert ? :failure_message : :negative_failure_message
     expectation = BeanCounter::EnqueuedExpectation.new(options)
@@ -216,8 +266,8 @@ module BeanCounter::TestAssertions
   end
 
 
-  # Builds tube expectation object, evaluates and makes appropriate assertion
-  # with appropriate failure message
+  # Builds tube expectation object, evaluates, and makes appropriate assertion
+  # with appropriate failure message.
   def tube_expectation(assertion_method, message_type, options)
     expectation = BeanCounter::TubeExpectation.new(options)
     match = expectation.matches?