games_dice 0.2.2 → 0.2.3

data/README.md

@@ -197,6 +197,12 @@ Returns the probability of a result less than the integer n.
     probabilities.p_lt( 17 )  # => 0.9953703703703
     probabilities.p_lt( 3 )   # => 0.0
 
+#### probabilities.expected
+
+Returns the mean result, weighted by probabality of each value.
+
+    probabilities.expected  # => 10.5 (rounded to nearest 1e-9)
+
 ## String Dice Descriptions
 
 The dice descriptions are a mini-language. A simple six-sided die is described like this:

data/lib/games_dice/bunch.rb

@@ -1,126 +1,159 @@
-# models a set of identical dice, that can be "rolled" and combined into a simple integer result. The
-# dice are identical in number of sides, and any re-roll or mapping rules that apply to them
+# This class models a number of identical dice, which may be either GamesDice::Die or
+# GamesDice::ComplexDie objects.
+#
+# An object of this class represents a fixed number of indentical dice that may be rolled and their
+# values summed to make a total for the bunch.
+#
+# @example The ubiquitous '3d6'
+#  d = GamesDice::Bunch.new( :ndice => 3, :sides => 6 )
+#  d.roll # => 14
+#  d.result # => 14
+#  d.explain_result # => "2 + 6 + 6 = 14"
+#  d.max # => 18
+#
+# @example Roll 5d10, and keep the best 2
+#  d = GamesDice::Bunch.new( :ndice => 5, :sides => 10 , :keep_mode => :keep_best, :keep_number => 2 )
+#  d.roll # => 18
+#  d.result # => 18
+#  d.explain_result # => "4, 9, 2, 9, 1. Keep: 9 + 9 = 18"
+#
+
 class GamesDice::Bunch
-  # attributes is a hash of symbols used to set attributes of the new Bunch object. Each
-  # attribute is explained in more detail in its own section. The following hash keys and values
-  # are mandatory:
-  #  :ndice
-  #  :sides
-  # The following are optional, and modify the behaviour of the Bunch object
-  #  :name
-  #  :prng
-  #  :rerolls
-  #  :maps
-  #  :keep_mode
-  #  :keep_number
-  # Any other keys provided to the constructor are ignored
-  def initialize( attributes )
-    @name = attributes[:name].to_s
-    @ndice = Integer(attributes[:ndice])
+  # The constructor accepts parameters that are suitable for either GamesDice::Die or GamesDice::ComplexDie
+  # and decides which of those classes to instantiate.
+  # @param [Hash] options
+  # @option options [Integer] :ndice Number of dice in the bunch, *mandatory*
+  # @option options [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
+  # @option options [String] :name Optional name for the bunch
+  # @option options [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
+  # @option options [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result for the die
+  # @option options [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
+  # @option options [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
+  # @option options [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
+  # @return [GamesDice::Bunch]
+  def initialize( options )
+    @name = options[:name].to_s
+    @ndice = Integer(options[:ndice])
     raise ArgumentError, ":ndice must be 1 or more, but got #{@ndice}" unless @ndice > 0
-    @sides = Integer(attributes[:sides])
+    @sides = Integer(options[:sides])
     raise ArgumentError, ":sides must be 1 or more, but got #{@sides}" unless @sides > 0
 
-    options = Hash.new
+    attr = Hash.new
 
-    if attributes[:prng]
+    if options[:prng]
       # We deliberately do not clone this object, it will often be intended that it is shared
-      prng = attributes[:prng]
+      prng = options[:prng]
       raise ":prng does not support the rand() method" if ! prng.respond_to?(:rand)
     end
 
     needs_complex_die = false
 
-    if attributes[:rerolls]
+    if options[:rerolls]
       needs_complex_die = true
-      options[:rerolls] = attributes[:rerolls].clone
+      attr[:rerolls] = options[:rerolls].clone
     end
 
-    if attributes[:maps]
+    if options[:maps]
       needs_complex_die = true
-      options[:maps] = attributes[:maps].clone
+      attr[:maps] = options[:maps].clone
     end
 
     if needs_complex_die
-      options[:prng] = prng
-      @single_die = GamesDice::ComplexDie.new( @sides, options )
+      attr[:prng] = prng
+      @single_die = GamesDice::ComplexDie.new( @sides, attr )
     else
       @single_die = GamesDice::Die.new( @sides, prng )
     end
 
-    case attributes[:keep_mode]
+    case options[:keep_mode]
     when nil then
       @keep_mode = nil
     when :keep_best then
       @keep_mode = :keep_best
-      @keep_number = Integer(attributes[:keep_number] || 1)
+      @keep_number = Integer(options[:keep_number] || 1)
     when :keep_worst then
       @keep_mode = :keep_worst
-      @keep_number = Integer(attributes[:keep_number] || 1)
+      @keep_number = Integer(options[:keep_number] || 1)
     else
-      raise ArgumentError, ":keep_mode can be nil, :keep_best or :keep_worst. Got #{attributes[:keep_mode].inspect}"
+      raise ArgumentError, ":keep_mode can be nil, :keep_best or :keep_worst. Got #{options[:keep_mode].inspect}"
     end
   end
 
-  # the string name as provided to the constructor, it will appear in explain_result
+  # Name to help identify bunch
+  # @return [String]
   attr_reader :name
 
-  # integer number of dice to roll (initially, before re-rolls etc)
+  # Number of dice to roll
+  # @return [Integer]
   attr_reader :ndice
 
-  # individual die that will be rolled, #ndice times, an GamesDice::Die or GamesDice::ComplexDie object.
+  # Individual die from the bunch
+  # @return [GamesDice::Die,GamesDice::ComplexDie]
   attr_reader :single_die
 
-  # may be nil, :keep_best or :keep_worst
+  # Can be nil, :keep_best or :keep_worst
+  # @return [Symbol,nil]
   attr_reader :keep_mode
 
-  # number of "best" or "worst" results to select when #keep_mode is not nil. This attribute is
-  # 1 by default if :keep_mode is supplied, or nil by default otherwise.
+  # Number of "best" or "worst" results to select when #keep_mode is not nil.
+  # @return [Integer,nil]
   attr_reader :keep_number
 
-  # after calling #roll, this is set to the final integer value from using the dice as specified
+  # Result of most-recent roll, or nil if no roll made yet.
+  # @return [Integer,nil]
   attr_reader :result
 
-  # Needs refinement. Returns best available string description of the bunch.
+  # @!attribute [r] label
+  # Description that will be used in explanations with more than one bunch
+  # @return [String]
   def label
     return @name if @name != ''
     return @ndice.to_s + 'd' + @sides.to_s
   end
 
-  # either nil, or an array of GamesDice::RerollRule objects that are assessed on each roll of #single_die
-  # Reroll types :reroll_new_die and :reroll_new_keeper do not affect the #single_die, but are instead
-  # assessed in this container object
+  # @!attribute [r] rerolls
+  # Sequence of re-roll rules, or nil if re-rolls are not required.
+  # @return [Array<GamesDice::RerollRule>, nil]
   def rerolls
     @single_die.rerolls
   end
 
-  # either nil, or an array of GamesDice::MapRule objects that are assessed on each result of #single_die (after rerolls are completed)
+  # @!attribute [r] maps
+  # Sequence of map rules, or nil if mapping is not required.
+  # @return [Array<GamesDice::MapRule>, nil]
   def maps
-    @single_die.rerolls
+    @single_die.maps
   end
 
-  # after calling #roll, this is an array of GamesDice::DieResult objects, one from each #single_die rolled,
+  # @!attribute [r] result_details
+  # After calling #roll, this is an array of GamesDice::DieResult objects. There is one from each #single_die rolled,
   # allowing inspection of how the result was obtained.
+  # @return [Array<GamesDice::DieResult>, nil] Sequence of GamesDice::DieResult objects.
   def result_details
     return nil unless @raw_result_details
     @raw_result_details.map { |r| r.is_a?(Fixnum) ? GamesDice::DieResult.new(r) : r }
   end
 
-  # minimum possible integer value
+  # @!attribute [r] min
+  # Minimum possible result from a call to #roll
+  # @return [Integer]
   def min
     n = @keep_mode ? [@keep_number,@ndice].min : @ndice
     return n * @single_die.min
   end
 
-  # maximum possible integer value
+  # @!attribute [r] max
+  # Maximum possible result from a call to #roll
+  # @return [Integer]
   def max
     n = @keep_mode ? [@keep_number,@ndice].min : @ndice
     return n * @single_die.max
   end
 
-  # returns a hash of value (Integer) => probability (Float) pairs. Warning: Some dice schemes
-  # cause this method to take a long time, and use a lot of memory. The worst-case offenders are
-  # dice schemes with a #keep_mode of :keep_best or :keep_worst.
+  # Calculates the probability distribution for the bunch. When the bunch is composed of dice with
+  # open-ended re-roll rules, there are some arbitrary limits imposed to prevent large amounts of
+  # recursion.
+  # @return [GamesDice::Probabilities] Probability distribution of bunch.
   def probabilities
     return @probabilities if @probabilities
     @probabilities_complete = true
@@ -158,7 +191,8 @@ class GamesDice::Bunch
     @probabilities = GamesDice::Probabilities.new( combined_probs )
   end
 
-  # simulate dice roll according to spec. Returns integer final total, and also stores it in #result
+  # Simulates rolling the bunch of identical dice
+  # @return [Integer] Sum of all rolled dice, or sum of all keepers
   def roll
     @result = 0
     @raw_result_details = []
@@ -184,6 +218,9 @@ class GamesDice::Bunch
     @result = use_dice.inject(0) { |so_far, die_result| so_far + die_result }
   end
 
+  # @!attribute [r] explain_result
+  # Explanation of result, or nil if no call to #roll yet.
+  # @return [String,nil]
   def explain_result
     return nil unless @result
 

data/lib/games_dice/dice.rb

@@ -1,12 +1,36 @@
-# models any combination of zero or more Bunches, plus a constant offset, summing them
-# to create a total result when rolled
+# This class models a combination of GamesDice::Bunch objects plus a fixed offset.
+#
+# An object of this class is a dice "recipe" that specifies the numbers and types of
+# dice that can be rolled to generate an integer value.
+#
+# @example '3d6+6' hitpoints, whatever that means in the game you are playing
+#  d = GamesDice::Dice.new( [{:ndice => 3, :sides => 6}], 6, 'Hit points' )
+#  d.roll # => 20
+#  d.result # => 20
+#  d.explain_result # => "3d6: 3 + 5 + 6 = 14. 14 + 6 = 20"
+#  d.probabilities.expected # => 16.5
+#
+# @example Roll d20 twice, take best result, and add 5.
+#  d = GamesDice::Dice.new( [{:ndice => 2, :sides => 20 , :keep_mode => :keep_best, :keep_number => 1}], 5 )
+#  d.roll # => 21
+#  d.result # => 21
+#  d.explain_result # => "2d20: 4, 16. Keep: 16. 16 + 5 = 21"
+#
 class GamesDice::Dice
-  # bunches is an Array of Hashes, each of which describes a GamesDice::Bunch
-  # and may contain any of the keys that can be used to initialize
-  # the Bunch, plus the following optional key:
-  #  :multiplier => any Integer, but typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
-  # offset is an Integer which will be added to the result when rolling all the bunches
-  # name can be any String, and is used to identify the dice being rolled.
+  # The first parameter is an array of values that are passed to GamesDice::Bunch constructors.
+  # @param [Array<Hash>] bunches Array of options for creating bunches
+  # @param [Integer] offset Total offset
+  # @param [String] name Optional label for the dice
+  # @option bunches [Integer] :ndice Number of dice in the bunch, *mandatory*
+  # @option bunches [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
+  # @option bunches [String] :name Optional name for the bunch
+  # @option bunches [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
+  # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result for the die
+  # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
+  # @option bunches [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
+  # @option bunches [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
+  # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
+  # @return [GamesDice::Dice]
   def initialize( bunches, offset = 0, name = '' )
     @name = name
     @offset = offset
@@ -15,24 +39,29 @@ class GamesDice::Dice
     @result = nil
   end
 
-  # the string name as provided to the constructor, it will appear in explain_result
+  # Name to help identify dice
+  # @return [String]
   attr_reader :name
 
-  # an array of GamesDice::Bunch objects that together describe all the dice and roll-altering
-  # rules that apply to the GamesDice::Dice object
+  # Bunches of dice that are components of the object
+  # @return [Array<GamesDice::Bunch>]
   attr_reader :bunches
 
-  # an array of Integers, used to multiply result from each bunch when total results are summed
+  # Multipliers for each bunch of identical dice. Typically 1 or -1 to represent groups of dice that
+  # are either added or subtracted from the total.
+  # @return [Array<Integer>]
   attr_reader :bunch_multipliers
 
-  # the integer offset that is added to the total result from all bunches
+  # Fixed offset added to sum of all bunches.
+  # @return [Integer]
   attr_reader :offset
 
-  # after calling #roll, this is set to the total integer value as calculated by simulating all the
-  # defined dice and their rules
+  # Result of most-recent roll, or nil if no roll made yet.
+  # @return [Integer,nil]
   attr_reader :result
 
-  # simulate dice roll. Returns integer final total, and also stores same value in #result
+  # Simulates rolling dice
+  # @return [Integer] Sum of all rolled dice
   def roll
     @result = @offset + @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
       m,b = mb
@@ -40,6 +69,9 @@ class GamesDice::Dice
     end
   end
 
+  # @!attribute [r] min
+  # Minimum possible result from a call to #roll
+  # @return [Integer]
   def min
     @min ||= @offset + @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
       m,b = mb
@@ -47,6 +79,9 @@ class GamesDice::Dice
     end
   end
 
+  # @!attribute [r] max
+  # Maximum possible result from a call to #roll
+  # @return [Integer]
   def max
     @max ||= @offset + @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
       m,b = mb
@@ -54,10 +89,17 @@ class GamesDice::Dice
     end
   end
 
+  # @!attribute [r] minmax
+  # Convenience method, same as [dice.min, dice.max]
+  # @return [Array<Integer>]
   def minmax
     [min,max]
   end
 
+  # Calculates the probability distribution for the dice. When the dice include components with
+  # open-ended re-roll rules, there are some arbitrary limits imposed to prevent large amounts of
+  # recursion.
+  # @return [GamesDice::Probabilities] Probability distribution of dice.
   def probabilities
     return @probabilities if @probabilities
     probs = @bunch_multipliers.zip(@bunches).inject( GamesDice::Probabilities.new( { @offset => 1.0 } ) ) do |probs, mb|
@@ -66,6 +108,8 @@ class GamesDice::Dice
     end
   end
 
+  # @!attribute [r] explain_result
+  # @return [String,nil] Explanation of result, or nil if no call to #roll yet.
   def explain_result
     return nil unless @result
     explanations = @bunches.map { |bunch| bunch.label + ": " + bunch.explain_result }

data/lib/games_dice/die_result.rb

@@ -1,16 +1,37 @@
-# returned by any complex die roll (i.e. one that may be subject to re-rolls or adjustments to each die)
+# This class models the output of GamesDice::ComplexDie.
+#
+# An object of the class represents the results of a roll of a ComplexDie, including any re-rolls and
+# value mapping.
+#
+# @example Building up a result manually
 #  dr = GamesDice::DieResult.new
-#  dr.add_roll(5)
-#  dr.add_roll(4,:reroll_add)
-#  dr.value # => 9
-#  dr.rolls # => [5,4]
-#  dr.roll_reasons # => [:basic,:reroll_add]
-#  dr + 5 # => 14
-# As the last example implies, GamesDice::DieResult objects coerce to the #value attribute
+#  dr.add_roll 5
+#  dr.add_roll 4, :reroll_replace
+#  dr.value # => 4
+#  dr.rolls # => [5, 4]
+#  dr.roll_reasons # => [:basic, :reroll_replace]
+#  # dr can behave as dr.value due to coercion and support for some operators
+#  dr + 6 # => 10
+#
+# @example Using a result from GamesDice::ComplexDie
+#  # An "exploding" six-sided die that needs a result of 8 to score "1 Success"
+#  d = GamesDice::ComplexDie.new( 6, :rerolls => [[6, :<=, :reroll_add]], :maps => [[8, :<=, 1, 'Success']] )
+#  # Generate result object by rolling the die
+#  dr = d.roll
+#  dr.rolls         # => [6, 3]
+#  dr.roll_reasons  # => [:basic, :reroll_add]
+#  dr.total         # => 9
+#  dr.value         # => 1
+#  dr.explain_value # => "[6+3] 9 Success"
+#
+
 class GamesDice::DieResult
   include Comparable
 
-  # first_roll_result is optional value of first roll of the die
+  # Creates new instance of GamesDice::DieResult. The object can be initialised "empty" or with a first result.
+  # @param [Integer,nil] first_roll_result Value for first roll of the die.
+  # @param [Symbol] first_roll_reason Reason for first roll of the die.
+  # @return [GamesDice::DieResult]
   def initialize( first_roll_result=nil, first_roll_reason=:basic )
     unless GamesDice::REROLL_TYPES.has_key?(first_roll_reason)
       raise ArgumentError, "Unrecognised reason for roll #{first_roll_reason}"
@@ -29,27 +50,31 @@ class GamesDice::DieResult
     @value = @total
   end
 
-  public
-
-  # array of integers
+  # The individual die rolls that combined to generate this result.
+  # @return [Array<Integer>] Un-processed values of each die roll used for this result.
   attr_reader :rolls
 
-  # array of symbol reasons for making roll
+  # The individual reasons for each roll of the die. See GamesDice::RerollRule for allowed values.
+  # @return [Array<Symbol>] Reasons for each die roll, indexes match the #rolls Array.
   attr_reader :roll_reasons
 
-  # combined numeric value of all rolls, nil if nothing calculated yet. Often the same number as
-  # #result, but may be different if there has been a call to #apply_map
+  # Combined result of all rolls, *before* mapping.
+  # @return [Integer,nil]
   attr_reader :total
 
-  # overall result of applying all rolls, nil if nothing calculated yet
+  # Combined result of all rolls, *after* mapping.
+  # @return [Integer,nil]
   attr_reader :value
 
-  # true if #apply_map has been called, and no more roll results added since
+  # Whether or not #value has been mapped from #total.
+  # @return [Boolean]
   attr_reader :mapped
 
-  # stores the value of a simple die roll. roll_result should be an Integer,
-  # roll_reason is an optional symbol description of why the roll was made
-  # #total and #value are calculated based on roll_reason
+  # Adds value from a new roll to the object. GamesDice::DieResult tracks reasons for the roll
+  # and makes the correct adjustment to the total so far. Any mapped value is cleared.
+  # @param [Integer] roll_result Value result from rolling the die.
+  # @param [Symbol] roll_reason Reason for rolling the die.
+  # @return [Integer] Total so far
   def add_roll( roll_result, roll_reason=:basic )
     unless GamesDice::REROLL_TYPES.has_key?(roll_reason)
       raise ArgumentError, "Unrecognised reason for roll #{roll_reason}"
@@ -83,14 +108,21 @@ class GamesDice::DieResult
     @value = @total
   end
 
-  # sets #value arbitrarily intended for use by GamesDice::MapRule objects
+  # Sets value arbitrarily, and notes that the value has been mapped. Used by GamesDice::ComplexDie
+  # when there are one or more GamesDice::MapRule objects to process for a die.
+  # @param [Integer] to_value Replacement value.
+  # @param [String] description Description of what the mapped value represents e.g. "Success"
+  # @return [nil]
   def apply_map( to_value, description = '' )
     @mapped = true
     @value = to_value
     @map_description = description
+    return
   end
 
-  # returns a string summary of how #value was obtained, showing all contributing rolls
+  # Generates a text description of how #value is determined. If #value has been mapped, includes the
+  # map description, but does not include the mapped value.
+  # @return [String] Explanation of #value.
   def explain_value
     text = ''
     if @rolls.length < 2
@@ -104,39 +136,46 @@ class GamesDice::DieResult
     return text
   end
 
-  # returns a string summary of the #total, including effect of any maps that been applied
+  # @!visibility private
+  # This is mis-named, it doesn't explain the total at all! It is used to generate summaries of keeper dice.
   def explain_total
     text = @total.to_s
     text += ' ' + @map_description if @mapped && @map_description && @map_description.length > 0
     return text
   end
 
+  # @!visibility private
   # all coercions simply use #value (i.e. nil or a Fixnum)
   def coerce(thing)
     @value.coerce(thing)
   end
 
+  # @!visibility private
   # addition uses #value
   def +(thing)
     @value + thing
   end
 
+  # @!visibility private
   # subtraction uses #value
   def -(thing)
     @value - thing
   end
 
+  # @!visibility private
   # multiplication uses #value
   def *(thing)
     @value * thing
   end
 
+  # @!visibility private
   # comparison <=> uses #value
   def <=>(other)
     self.value <=> other
   end
 
-  # implements a deep clone (used for recursive probability calculations)
+  # This is a deep clone, all attributes are cloned.
+  # @return [GamesDice::DieResult]
   def clone
     cloned = GamesDice::DieResult.new()
     cloned.instance_variable_set('@rolls', @rolls.clone)

data/lib/games_dice/map_rule.rb

@@ -48,11 +48,11 @@ class GamesDice::MapRule
   # @return [Integer,Range,Object] Object that receives (#trigger_op, die_result)
   attr_reader :trigger_value
 
-  # Mapped value.
+  # Value that a die will use after the value has been mapped.
   # @return [Integer]
   attr_reader :mapped_value
 
-  # Name for mapped value.
+  # Name for mapped value, used in explanations.
   # @return [String]
   attr_reader :mapped_name
 

data/lib/games_dice/parser.rb

@@ -1,6 +1,11 @@
 require 'parslet'
 
-# converts string dice descriptions to data usable for the GamesDice::Dice constructor
+# Based on the parslet gem, this class defines the dice mini-language used by GamesDice.create
+#
+# An instance of this class is a parser for the language. There are no user-definable instance
+# variables.
+#
+
 class GamesDice::Parser < Parslet::Parser
 
   # Parslet rules that define the dice string grammar.
@@ -62,6 +67,10 @@ class GamesDice::Parser < Parslet::Parser
   rule(:expressions) { dice_expression.repeat.as(:bunches) }
   root :expressions
 
+  # Parses a string description in the dice mini-language, and returns data for feeding into
+  # GamesDice::Dice constructore.
+  # @param [String] dice_description Text to parse e.g. '1d6'
+  # @return [Hash] Analysis of dice_description
   def parse dice_description
     dice_description = dice_description.to_s.strip
     # Force first item to start '+' for simpler parse rules

data/lib/games_dice/probabilities.rb

@@ -1,49 +1,84 @@
-# utility class for calculating with probabilities for reuslts from GamesDice objects
+# This class models probability distributions for dice systems.
+#
+# An object of this class represents a single distribution, which might be the result of a complex
+# combination of dice.
+#
+# @example Distribution for a six-sided die
+#  probs = GamesDice::Probabilities.for_fair_die( 6 )
+#  probs.min # => 1
+#  probs.max # => 6
+#  probs.expected # => 3.5
+#  probs.p_ge( 4 ) # => 0.5
+#
+# @example Adding two distributions
+#  pd6 = GamesDice::Probabilities.for_fair_die( 6 )
+#  probs = GamesDice::Probabilities.add_distributions( pd6, pd6 )
+#  probs.min # => 2
+#  probs.max # => 12
+#  probs.expected # => 7.0
+#  probs.p_ge( 10 ) # => 0.16666666666666669
+#
 class GamesDice::Probabilities
-  # prob_hash is a Hash with each key as an Integer, and the associated value being the probability
-  # of getting that value. It is not validated. Avoid using the default constructor if
-  # one of the factory methods or calculation methods already does what you need.
+
+  # Creates new instance of GamesDice::Probabilities.
+  # @param [Hash] prob_hash A hash representation of the distribution, each key is an integer result,
+  #   and the matching value is probability of getting that result
+  # @return [GamesDice::Probabilities]
   def initialize( prob_hash = { 0 => 1.0 } )
-    # This should *probably* be validated in future
+    # This should *probably* be validated in future, but that would impact performance
     @ph = prob_hash
   end
 
-  # the Hash representation of probabilities. TODO: Hide this from public interface, but make it available
-  # to factory methods
+  # @!visibility private
+  # the Hash representation of probabilities.
   attr_reader :ph
 
-  # a clone of probability data (as provided to constructor), safe to pass to methods that modify in place
+  # A hash representation of the distribution. Each key is an integer result,
+  # and the matching value is probability of getting that result. A new hash is generated on each
+  # call to this method.
+  # @return [Hash]
   def to_h
     @ph.clone
   end
 
+  # @!attribute [r] min
+  # Minimum result in the distribution
+  # @return [Integer]
   def min
     (@minmax ||= @ph.keys.minmax )[0]
   end
 
+  # @!attribute [r] max
+  # Maximum result in the distribution
+  # @return [Integer]
   def max
     (@minmax ||= @ph.keys.minmax )[1]
   end
 
-  # returns mean expected value as a Float
+  # @!attribute [r] expected
+  # Expected value of distribution.
+  # @return [Float]
   def expected
     @expected ||= @ph.inject(0.0) { |accumulate,p| accumulate + p[0] * p[1] }
   end
 
-  # returns Float probability fram Range (0.0..1.0) that a value chosen from the distribution will
-  # be equal to target integer
+  # Probability of result equalling specific target
+  # @param [Integer] target
+  # @return [Float] in range (0.0..1.0)
   def p_eql target
     @ph[ Integer(target) ] || 0.0
   end
 
-  # returns Float probability fram Range (0.0..1.0) that a value chosen from the distribution will
-  # be a number greater than target integer
+  # Probability of result being greater than specific target
+  # @param [Integer] target
+  # @return [Float] in range (0.0..1.0)
   def p_gt target
     p_ge( Integer(target) + 1 )
   end
 
-  # returns Float probability fram Range (0.0..1.0) that a value chosen from the distribution will
-  # be a number greater than or equal to target integer
+  # Probability of result being equal to or greater than specific target
+  # @param [Integer] target
+  # @return [Float] in range (0.0..1.0)
   def p_ge target
     target = Integer(target)
     return @prob_ge[target] if @prob_ge && @prob_ge[target]
@@ -54,7 +89,9 @@ class GamesDice::Probabilities
     @prob_ge[target] = @ph.select {|k,v| target <= k}.inject(0.0) {|so_far,pv| so_far + pv[1] }
   end
 
-  # returns probability than a roll will produce a number less than or equal to target integer
+  # Probability of result being equal to or less than specific target
+  # @param [Integer] target
+  # @return [Float] in range (0.0..1.0)
   def p_le target
     target = Integer(target)
     return @prob_le[target] if @prob_le && @prob_le[target]
@@ -65,12 +102,16 @@ class GamesDice::Probabilities
     @prob_le[target] = @ph.select {|k,v| target >= k}.inject(0.0) {|so_far,pv| so_far + pv[1] }
   end
 
-  # returns probability than a roll will produce a number less than target integer
+  # Probability of result being less than specific target
+  # @param [Integer] target
+  # @return [Float] in range (0.0..1.0)
   def p_lt target
     p_le( Integer(target) - 1 )
   end
 
-  # constructor returns probability distrubution for a simple fair die
+  # Distribution for a die with equal chance of rolling 1..N
+  # @param [Integer] sides Number of sides on die
+  # @return [GamesDice::Probabilities]
   def self.for_fair_die sides
     sides = Integer(sides)
     raise ArgumentError, "sides must be at least 1" unless sides > 0
@@ -80,8 +121,11 @@ class GamesDice::Probabilities
     GamesDice::Probabilities.new( h )
   end
 
-  # adding two probability distributions calculates a new distribution, representing what would
-  # happen if you created a random number using the sum of numbers from both distributions
+  # Combines two distributions to create a third, that represents the distribution created when adding
+  # results together.
+  # @param [GamesDice::Probabilities] pd_a First distribution
+  # @param [GamesDice::Probabilities] pd_b Second distribution
+  # @return [GamesDice::Probabilities]
   def self.add_distributions pd_a, pd_b
     h = {}
     pd_a.ph.each do |ka,pa|
@@ -94,8 +138,13 @@ class GamesDice::Probabilities
     GamesDice::Probabilities.new( h )
   end
 
-  # adding two probability distributions calculates a new distribution, representing what would
-  # happen if you created a random number using the sum of numbers from both distributions
+  # Combines two distributions with multipliers to create a third, that represents the distribution
+  # created when adding weighted results together.
+  # @param [Integer] m_a Weighting for first distribution
+  # @param [GamesDice::Probabilities] pd_a First distribution
+  # @param [Integer] m_b Weighting for second distribution
+  # @param [GamesDice::Probabilities] pd_b Second distribution
+  # @return [GamesDice::Probabilities]
   def self.add_distributions_mult m_a, pd_a, m_b, pd_b
     h = {}
     pd_a.ph.each do |ka,pa|
@@ -108,4 +157,4 @@ class GamesDice::Probabilities
     GamesDice::Probabilities.new( h )
   end
 
-end # class Dice
+end # class GamesDice::Probabilities

data/lib/games_dice/version.rb

@@ -1,3 +1,3 @@
 module GamesDice
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/spec/bunch_spec.rb

@@ -1,4 +1,5 @@
 require 'games_dice'
+require 'helpers'
 
 describe GamesDice::Bunch do
 

data/spec/complex_die_spec.rb

@@ -1,4 +1,5 @@
 require 'games_dice'
+require 'helpers'
 
 describe GamesDice::ComplexDie do
 

data/spec/die_spec.rb

@@ -1,4 +1,5 @@
 require 'games_dice'
+require 'helpers'
 
 describe GamesDice::Die do
 

data/spec/probability_spec.rb

@@ -1,4 +1,5 @@
 require 'games_dice'
+require 'helpers'
 
 describe GamesDice::Probabilities do
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: games_dice
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-10 00:00:00.000000000 Z
+date: 2013-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -144,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2482711703426352461
+      hash: 1797445249921181101
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -153,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2482711703426352461
+      hash: 1797445249921181101
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24