bean_counter 0.0.3 → 0.0.4

data/README.md

@@ -312,7 +312,7 @@ verify that the exports tube is paused:
 For more detailed explanations and more examples make sure to check out the
 docs, expectations, and respective tests:
 
-- [docs](http://rubydoc.info/gems/bean_counter/0.0.3/frames)
+- [docs](http://rubydoc.info/gems/bean_counter/0.0.4/frames)
 - [enqueued_expectation](https://github.com/gemeraldbeanstalk/bean_counter/tree/master/lib/bean_counter/enqueued_expectation.rb)
 - [tube_expectation](https://github.com/gemeraldbeanstalk/bean_counter/tree/master/lib/bean_counter/tube_expectation.rb)
 - [test_assertions](https://github.com/gemeraldbeanstalk/bean_counter/tree/master/lib/bean_counter/test_assertions.rb)

data/lib/bean_counter/core.rb

@@ -3,38 +3,52 @@ module BeanCounter
   # Use StalkClimberStrategy by default because it works with standard Beanstalkd
   DEFAULT_STRATEGY = :'BeanCounter::Strategy::StalkClimberStrategy'
 
-  class << self
-    # Beanstalkd server urls to be used by BeanCounter
-    attr_writer :beanstalkd_url
+  # Sets the Beanstalkd server URLs to be used by BeanCounter.
+  #
+  # @param value [String, Array<String>] The new value to to assign to beanstalkd_urls
+  # @return [Object] Returns the value given
+  def self.beanstalkd_url=(value)
+    @beanstalkd_url = value
   end
 
-  # :call-seq:
-  #   beanstalkd_url() => Array[String]
-  #
-  # Returns an array of parsed beanstalkd urls.
-  # Server urls provided via the environment variable +BEANSTALKD_URL+ are given
+  # Returns an Array of parsed Beanstalkd URLs.
+  # Server URLs provided via the environment variable `BEANSTALKD_URL` are given
   # precedence. When setting beanstalkd_url from the environment, urls are
-  # expected in a comma separated list. If ENV['BEANSTALKD_URL'] is not set
-  # BeanCounter::beanstalkd_url is checked and parsed next. Finally, if
-  # BeanCounter::beanstalkd_url has not been set, the configuration for Beaneater is
-  # checked and parsed. If no beanstalkd_url can be determined a RuntimeError is raised.
-  # URLs can be provided in any of three supported formats:
-  # * localhost (host only)
-  # * 192.168.1.100:11300 (host and port)
-  # * beanstalk://127.0.0.1:11300 (host and port prefixed by beanstalk scheme)
+  # expected in a comma separated list. If `ENV['BEANSTALKD_URL']` is not set,
+  # the BeanCounter.beanstalkd_url instance variable is checked and parsed next.
+  # Finally, if the BeanCounter.beanstalkd_url instance variable has not been
+  # set, the configuration for Beaneater is checked and parsed. If no
+  # beanstalkd_url can be determined a RuntimeError is raised.
+  # Beanstalkd URLs can be provided in any of three supported formats shown in
+  # in the examples below.
   #
   # In short, a host is the only required component. If no port is provided, the default
-  # beanstalkd port of 11300 is assumed. If a scheme other than beanstalk is provided
-  # a StalkClimber::ConnectionPool::InvalidURIScheme error is raised.
+  # beanstalkd port of 11300 is assumed. If a URI scheme other than beanstalk
+  # is provided the strategy in use will likely raise an error.
+  #
+  # @return [Array<String>] An Array of Beanstalkd URLs.
+  # @example Valid beanstalkd_url formats
+  #   # host only:
+  #   'localhost'
+  #
+  #   # host and port:
+  #   '192.168.1.100:11300'
+  #
+  #   # host and port prefixed by beanstalk URI scheme:
+  #   'beanstalk://127.0.0.1:11300'
+  #
+  # @example BeanCounter.beanstalkd_url provided via ENV['BEANSTALKD_URL']
+  #   # $ BEANSTALKD_URL='127.0.0.1,beanstalk://localhost:11300,localhost:11301' rake test
   #
-  #   $ BEANSTALKD_URL='127.0.0.1,beanstalk://localhost:11300,localhost:11301' rake test
   #   BeanCounter.beanstalkd_url
   #     #=> ['127.0.0.1', 'beanstalk://localhost:11300', 'localhost:11301']
   #
+  # @example BeanCounter.beanstalkd_url set explicitly
   #   BeanCounter.beanstalkd_url = 'beanstalk://localhost'
   #   BeanCounter.beanstalkd_url
   #     #=> 'beanstalk://localhost'
   #
+  # @example BeanCounter.beanstalkd_url provided by Beaneater
   #   Beaneater.configure do |config|
   #     config.beanstalkd_url = ['localhost', 'localhost:11301']
   #   end
@@ -46,33 +60,35 @@ module BeanCounter
     @hosts_from_env = @hosts_from_env.split(',').map!(&:strip) unless @hosts_from_env.nil?
     beanstalkd_url = @hosts_from_env || @beanstalkd_url || Beaneater.configuration.beanstalkd_url
     raise 'Could not determine beanstalkd url' if beanstalkd_url.to_s == ''
-    return beanstalkd_url
+    return beanstalkd_url.is_a?(Array) ? beanstalkd_url : [beanstalkd_url]
   end
 
 
-  # :call-seq:
-  #   default_strategy() => subclass of BeanCounter::Strategy
+  # Returns a previously materialized strategy or materializes a new default
+  # strategy for use.
+  #
+  # See {BeanCounter::Strategy.materialize_strategy} for more information on the
+  # materialization process.
   #
-  # Return a previously materialized default strategy or materialize a new default
-  # strategy for use. See BeanCounter::Strategy::materialize_strategy for more
-  # information on the materialization process.
+  # @see BeanCounter::Strategy.materialize_strategy
+  # @return [BeanCounter::Strategy] An existing or newly materialized default strategy
   def self.default_strategy
     return @default_strategy ||= BeanCounter::Strategy.materialize_strategy(DEFAULT_STRATEGY)
   end
 
 
-  # :call-seq:
-  #   reset!(tube_name = nil) => Boolean
-  # Uses the strategy to delete all jobs from the +tube_name+ tube. If +tube_name+
-  # is not provided, all jobs on the beanstalkd server are deleted.
+  # Uses strategy to delete all jobs from the beanstalkd pool or from the tube
+  #   specified by `tube_name`.
   #
   # It should be noted that jobs that are reserved can only be deleted by the
   # reserving connection and thus cannot be deleted via this method. As such,
   # care may need to be taken to ensure that jobs are not left in a reserved
   # state.
   #
-  # Returns true if all encountered jobs were deleted successfully. Returns
-  # false if any of the jobs enumerated could not be deleted.
+  # @param tube_name [String] a particular tube to clear all jobs from. If not
+  #   given, all jobs in the Beanstalkd pool will be} deleted.
+  # @return [Boolean] Returns true if all encountered jobs were deleted successfully. Returns
+  #   false if any of the jobs enumerated could not be deleted.
   def self.reset!(tube_name = nil)
     partial_failure = false
     strategy.jobs.each do |job|
@@ -83,19 +99,26 @@ module BeanCounter
   end
 
 
-  # Returns a list of known subclasses of BeanCounter::Strategy.
-  # Typically this list represents the strategies available for interacting
-  # with beanstalkd.
+  # Returns a list of known subclasses of BeanCounter::Strategy. Typically this
+  # list represents the strategies available for interacting with Beanstalkd.
+  #
+  # @return [Array<BeanCounter::Strategy>] Returns a list of known subclasses of
+  #   BeanCounter::Strategy
   def self.strategies
     return BeanCounter::Strategy.strategies
   end
 
 
-  # Sets the strategy that BeanCounter should use when interacting with
-  # beanstalkd. The value provided for +strategy_identifier+ will be used to
+  # Sets the strategy that BeanCounter should use when interacting with Beanstalkd.
+  # The value provided for `strategy_identifier` will be used to
   # materialize an instance of the matching strategy class. If the provided
-  # +strategy_identifier+ is nil, any existing strategy will be cleared and
-  # the next call to BeanCounter::strategy will use the default strategy.
+  # `strategy_identifier` is nil, any existing strategy will be cleared and
+  # the next call to BeanCounter.strategy will use the default strategy.
+  #
+  # @param strategy_identifier [Object] A class or an Object that responds to
+  #   :to_sym identifying the subclass of BeanCounter::Strategy to use
+  #   when communicating with the beanstalkd pool
+  # @return [Object] Returns the value given
   def self.strategy=(strategy_identifier)
     if strategy_identifier.nil?
       @strategy = nil
@@ -105,9 +128,12 @@ module BeanCounter
   end
 
 
-  # Returns a previously materialized strategy if one exists. If no previous
-  # strategy exists, a new instance of the default strategy is instantiated
-  # and returned.
+  # Returns a previously materialized strategy or instantiates a new instance
+  # of the default strategy. If no previous strategy exists, a new instance of
+  # the default strategy is instantiated and returned.
+  #
+  # @return [BeanCounter::Strategy] Returns the existing strategy or a new
+  #   instance of the default strategy
   def self.strategy
     return @strategy ||= default_strategy.new
   end

data/lib/bean_counter/enqueued_expectation.rb

@@ -4,18 +4,27 @@ class BeanCounter::EnqueuedExpectation
 
   def_delegators BeanCounter, :strategy
 
-  # The value that the expectation expects
+  # The Hash of options given at instantiation that the expectation expects when
+  # matching.
+  # @return [Hash]
   attr_reader :expected
 
   # The number of matching jobs the expectation expects
+  # @return [Numeric, Range]
   attr_reader :expected_count
 
   # The jobs found by the expecation during matching
+  # @return [Array<Strategy::Job>]
   attr_reader :found
 
 
   # Iterates over the provided collection searching for jobs matching the
-  # Hash of expected options provided at instantiation.
+  # Hash of expected options provided during instantiation.
+  #
+  # @param collection [Array<Strategy::Job>] A collection of jobs as
+  #   implemented by the strategy to evaluate for a match.
+  # @return [Boolean] true if the collection matches the expected options and
+  #   count
   def collection_matcher(collection)
     @found = collection.send(expected_count? ? :select : :detect) do |job|
       strategy.job_matches?(job, expected)
@@ -28,13 +37,19 @@ class BeanCounter::EnqueuedExpectation
 
 
   # Returns a Boolean indicating whether a specific number of jobs are expected.
+  #
+  # @return [Boolean] true if a specifc number of jobs are expected, otherwise
+  #   false
   def expected_count?
     return !!expected_count
   end
 
 
   # Builds the failure message used in the event of a positive expectation
-  # failure
+  # failure.
+  #
+  # @return [String] The failure message for use in the event of a positive
+  #   expectation failure.
   def failure_message
     if found.nil?
       found_count = 'none'
@@ -52,18 +67,28 @@ class BeanCounter::EnqueuedExpectation
   end
 
 
-  # Create a new enqueued expectation. Uses the given +expected+ Hash to determine
+  # Create a new enqueued expectation. Uses the given `expected` Hash to determine
   # if any jobs are enqueued that match the expected options.
   #
-  # Each _key_ in +expected+ 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 `expected` 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`.
   #
-  # +expected+ may additionally include a _count_ key of 'count' or :count that
+  # `expected` may additionally include a `count` key of 'count' or :count that
   # can be used to specify that a particular number of matching jobs are found.
   #
-  # See BeanCounter::TestAssertions and/or BeanCounter::SpecMatchers for more information.
+  # See {BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES} for a list of
+  #   attributes that can be used when matching.
+  #
+  # @see BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::TestAssertions
+  # @see BeanCounter::SpecMatchers
+  # @param expected
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options expected when evaluating match
+  # @option expected [Numeric, Range] :count (nil) A particular number of matching
+  #   jobs expected
   def initialize(expected)
     @expected = expected
     @expected_count = [expected.delete(:count), expected.delete('count')].compact.first
@@ -73,12 +98,12 @@ class BeanCounter::EnqueuedExpectation
   # Checks the beanstalkd pool for jobs matching the Hash of expected options
   # provided at instantiation.
   #
-  # If no _count_ option is provided, the expectation succeeds if any job is found
+  # If no `count` option is provided, the expectation succeeds if any job is found
   # that matches all of the expected options. If no jobs are found that match the
   # expected options, the expecation fails.
   #
-  # If a _count_ option is provided the expectation 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 expectation 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 expecation fails. The use of ===
   # allows for more advanced comparisons using Procs, Ranges, Regexps, etc.
   #
@@ -86,8 +111,17 @@ class BeanCounter::EnqueuedExpectation
   # in use for more detailed information on how it is determined whether or not
   # a job matches the options expected.
   #
-  # See also BeanCounter::TestAssertions and/or BeanCounter::SpecMatchers for additional
-  # information.
+  # See {BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES} for a list of
+  #   attributes that can be used when matching.
+  #
+  # @see BeanCounter::Strategy::MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::TestAssertions
+  # @see BeanCounter::SpecMatchers
+  # @param given [Proc] If a Proc is provided, only jobs enqueued during the
+  #   execution of the Proc are considered when looking for a match. Otherwise
+  #   all jobs available to the strategy will be evaluated for a match.
+  # @return [Boolean] If a match is found, returns true. Otherwise, returns
+  #   false.
   def matches?(given = nil)
     if given.kind_of?(Proc)
       return proc_matcher(given)
@@ -99,6 +133,9 @@ class BeanCounter::EnqueuedExpectation
 
   # Builds the failure message used in the event of a negative expectation
   # failure
+  #
+  # @return [String] The failure message for use in the event of a negative
+  #   expectation failure.
   def negative_failure_message
     return '' if found.nil? || found == []
 
@@ -119,13 +156,17 @@ class BeanCounter::EnqueuedExpectation
   end
 
 
-  # Monitors the beanstalkd pool for new jobs enqueued during the provided
-  # block than passes any collected jobs to the collection matcher to determine
-  # if any jobs were enqueued that match the expected options provided at
-  # instantiation
+  # Evaluates jobs enqueued during the execution of the provided block to
+  # determine if any jobs were enqueued that match the expected options provided
+  # at instantiation
+  #
+  # @param block [Proc] A Proc that when executed should demonstrate that
+  #   expected behavior.
+  # @return [Boolean] If the jobs enqueued during the execution of the `block`
+  #   include a match, returns true. Otherwise, returns false.
   def proc_matcher(block)
     new_jobs = strategy.collect_new_jobs(&block)
-    collection_matcher(new_jobs)
+    return collection_matcher(new_jobs)
   end
 
 end

data/lib/bean_counter/spec_matchers.rb

@@ -1,23 +1,36 @@
 module BeanCounter::SpecMatchers
 
-  # Creates a new BeanCounter::EnqueuedExpectation with +expected+ stored for
-  # later use when matching. Most of the time the value provided for +expected+
-  # will be ignored, the only exception is when +expected+ is given a block.
-  # When a block is provided for +expected+, only jobs enqueued during the
+  # Creates a new {BeanCounter::EnqueuedExpectation} with `expected` stored for
+  # later use when matching. Most of the time the value provided for `expected`
+  # will be ignored, the only exception is when `expected` is given a block.
+  # When a block is provided for `expected`, only jobs enqueued during the
   # execution of the block will be considered when matching.
   #
-  # See BeanCounter::EnqueuedExpectation for additional information and usage
+  # See {BeanCounter::EnqueuedExpectation} for additional information and usage
   # patterns.
+  #
+  # @see BeanCounter::EnqueuedExpectation
+  # @param expected
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   options used for evaluating match.
+  # @return [BeanCounter::EnqueuedExpectation] an expectation to be used for
+  #   matching.
   def have_enqueued(expected)
     BeanCounter::EnqueuedExpectation.new(expected)
   end
 
-  # Creates a new BeanCounter::TubeExpectation with +expected+ stored for
-  # later use when matching. However, +expected+ is never used when matching.
+  # Creates a new {BeanCounter::TubeExpectation} with `expected` stored for
+  # later use when matching. However, `expected` is never used when matching.
   # Instead, all tubes are matched against until a match is found.
   #
-  # See BeanCounter::TubeExpectation for additional information and usage
+  # See {BeanCounter::TubeExpectation} for additional information and usage
   # patterns.
+  #
+  # @param expected
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   options used for evaluating match.
+  # @see BeanCounter::TubeExpectation
+  # @return [BeanCounter::TubeExpectation] an expectation to be used for matching.
   def have_tube(expected)
     BeanCounter::TubeExpectation.new(expected)
   end

data/lib/bean_counter/strategies/stalk_climber_strategy.rb

@@ -16,24 +16,26 @@ class BeanCounter::Strategy::StalkClimberStrategy < BeanCounter::Strategy
     attr_methods
   end
 
-  # Default tube used by StalkClimber when probing the beanstalkd pool
+  # Default tube used by StalkClimber when probing the Beanstalkd pool
   TEST_TUBE = 'bean_counter_stalk_climber_test'
 
-  # The tube that will be used by StalkClimber when probing the beanstalkd pool.
-  # Uses TEST_TUBE if no value provided.
+  # The tube that will be used by StalkClimber when probing the Beanstalkd pool.
+  # Uses {TEST_TUBE} if no value provided.
   attr_writer :test_tube
 
   def_delegators :climber, :jobs, :tubes
 
 
-  # :call-seq:
-  #   collect_new_jobs { block } => Array[StalkClimber::Job]
-  #
-  # Collects all jobs enqueued during the execution of the provided +block+.
+  # Collects all jobs enqueued during the execution of the provided `block`.
   # Returns an Array of StalkClimber::Job.
   #
-  # Fulfills Strategy#collect_new_jobs contract. See Strategy#collect_new_jobs
-  # for more information.
+  # Fulfills {BeanCounter::Strategy#collect_new_jobs} contract.
+  #
+  # @see BeanCounter::Strategy#collect_new_jobs
+  # @yield Nothing is yielded to the provided `block`
+  # @raise [ArgumentError] if a block is not provided.
+  # @return [Array<StalkClimber::Job>] all jobs enqueued during the execution
+  #   of the provided `block`
   def collect_new_jobs
     raise ArgumentError, 'Block required' unless block_given?
 
@@ -49,15 +51,16 @@ class BeanCounter::Strategy::StalkClimberStrategy < BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   delete_job(job) => Boolean
-  #
-  # Attempts to delete the given StalkClimber::Job +job+. Returns true if
-  # deletion succeeds or if +job+ does not exist. Returns false if +job+ could
+  # Attempts to delete the given StalkClimber::Job `job`. Returns true if
+  # deletion succeeds or if `job` does not exist. Returns false if `job` could
   # not be deleted (typically due to it being reserved by another connection).
   #
-  # Fulfills Strategy#delete_job contract. See Strategy#delete_job for more
-  # information.
+  # Fulfills {BeanCounter::Strategy#delete_job} contract.
+  #
+  # @see BeanCounter::Strategy#delete_job
+  # @param job [StalkClimber::Job] the job to be deleted
+  # @return [Boolean] If the given job was successfully deleted or does not
+  #   exist, returns true. Otherwise returns false.
   def delete_job(job)
     job.delete
     return true
@@ -66,67 +69,84 @@ class BeanCounter::Strategy::StalkClimberStrategy < BeanCounter::Strategy
   end
 
 
-  # :call-seq:
-  #   job_matches?(job, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
+  # Returns a Boolean indicating whether or not the provided Sta`kClimber::Job
+  # `job` matches the given Hash of `options`.
   #
-  # Returns a boolean indicating whether or not the provided StalkClimber::Job
-  # +job+ matches the given Hash of +options.
+  # See {MATCHABLE_JOB_ATTRIBUTES} for a list of
+  # attributes that can be used when matching.
   #
-  # Fulfills Strategy#job_matches? contract. See Strategy#job_matches? for more
-  # information.
-  def job_matches?(job, opts = {})
-    return matcher(MATCHABLE_JOB_ATTRIBUTES, job, opts)
+  # Fulfills {BeanCounter::Strategy#job_matches?} contract.
+  #
+  # @see MATCHABLE_JOB_ATTRIBUTES
+  # @see BeanCounter::Strategy#job_matches?
+  # @param job [StalkClimber::Job] the job to evaluate if matches.
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   Options to be used to evaluate a match.
+  # @return [Boolean] If job matches the provided options, returns true.
+  #   Otherwise, returns false.
+  def job_matches?(job, options = {})
+    return matcher(MATCHABLE_JOB_ATTRIBUTES, job, options)
   end
 
 
-  # :call-seq:
-  #   pretty_print_job(job) => String
-  #
-  # Returns a String representation of the StalkClimber::Job +job+ in a pretty,
+  # Returns a String representation of the StalkClimber::Job `job` in a pretty,
   # human readable format.
   #
-  # Fulfills Strategy#pretty_print_job contract. See Strategy#pretty_print_job
-  # for more information.
+  # Fulfills {BeanCounter::Strategy#pretty_print_job} contract.
+  #
+  # @see BeanCounter::Strategy#pretty_print_job
+  # @param job [StalkClimber::Job] the job to print in a more readable format.
+  # @return [String] A more human-readable representation of `job`.
   def pretty_print_job(job)
     return job.to_h.to_s
   end
 
 
-  # :call-seq:
-  #   pretty_print_tube(tube) => String
+  # Returns a String representation of `tube` in a pretty, human readable format.
   #
-  # Returns a String representation of +tube+ in a pretty, human readable format.
+  # Fulfills {BeanCounter::Strategy#pretty_print_tube} contract.
   #
-  # Fulfills Strategy#pretty_print_tube contract. See Strategy#pretty_print_tube
-  # for more information.
+  # @see BeanCounter::Strategy#pretty_print_tube
+  # @param tube [StalkClimber::Tube] the tube to print in a more readable format.
+  # @return [String] A more human-readable representation of `tube`.
   def pretty_print_tube(tube)
     return tube.to_h.to_s
   end
 
 
-  # :call-seq:
-  #   tube_matches?(tube, options => {Symbol,String => Numeric,Proc,Range,Regexp,String}) => Boolean
+  # Returns a boolean indicating whether or not the provided StalkClimber `tube`
+  # matches the given Hash of `options`.
+  #
+  # See {MATCHABLE_TUBE_ATTRIBUTES} for a list of attributes that can be used
+  # when evaluating a match.
   #
-  # Returns a boolean indicating whether or not the provided StalkClimber +tube+
-  # matches the given Hash of +options.
+  # Fulfills {BeanCounter::Strategy#tube_matches?} contract.
   #
-  # Fulfills Strategy#tube_matches? contract. See Strategy#tube_matches? for
-  # more information.
-  def tube_matches?(tube, opts = {})
-    return matcher(MATCHABLE_TUBE_ATTRIBUTES, tube, opts)
+  # @see BeanCounter::Strategy#tube_matches?
+  # @param tube [StalkClimber::Tube] the tube to evaluate a match against.
+  # @param options
+  #   [Hash{String, Symbol => Numeric, Proc, Range, Regexp, String, Symbol}]
+  #   a Hash of options to use when evaluating a match.
+  # @return [Boolean] If `tube` matches against the provided options, returns
+  #   true. Otherwise returns false.
+  def tube_matches?(tube, options = {})
+    return matcher(MATCHABLE_TUBE_ATTRIBUTES, tube, options)
   end
 
   private
 
   # StalkClimber instance used to climb/crawl beanstalkd pool
+  # @return [StalkClimber::Climber]
   def climber
     return @climber ||= StalkClimber::Climber.new(BeanCounter.beanstalkd_url, test_tube)
   end
 
 
-  # Given the set of valid attributes, +valid_attributes+, determines if every
-  # _value_ of +opts+ evaluates to true when compared to the attribute of
-  # +matchable+ identified by the corresponding +opts+ _key_.
+  # Given the set of valid attributes, `valid_attributes`, determines if every
+  # `value` of `opts` evaluates to true when compared to the attribute of
+  # `matchable` identified by the corresponding `opts` `key`.
+  # @return [Boolean]
   def matcher(valid_attributes, matchable, opts = {})
     # Refresh state/stats before checking match
     return false unless matchable.exists?
@@ -137,6 +157,7 @@ class BeanCounter::Strategy::StalkClimberStrategy < BeanCounter::Strategy
 
 
   # Simplify lookup of what method to call to retrieve requested stat
+  # @return [Symbol]
   def stats_method_name(stats_attr)
     return STATS_METHOD_NAMES[stats_attr.to_sym]
   end