Improve docs for Prime.{prime_division,int_from_prime_division}

README.md

@@ -33,8 +33,9 @@ Prime.prime?(7)           #=> true
 8.prime?                  #=> false
 
 # Factorization in prime numbers
-Prime.prime_division(779)                           #=> [[19, 1], [41, 1]]
-Prime.int_from_prime_division([[19, 1], [41, 1]])   #=> 779
+Prime.prime_division(8959)                          #=> [[17, 2], [31, 1]]
+Prime.int_from_prime_division([[17, 2], [31, 1]])   #=> 8959
+17**2 * 31                                          #=> 8959
 ```
 
 ## Contributing

lib/prime.rb

@@ -174,17 +174,23 @@ def prime?(value, generator = Prime::Generator23.new)
 
   # Re-composes a prime factorization and returns the product.
   #
+  # For the decomposition:
+  #
+  #   [[p_1, e_1], [p_2, e_2], ..., [p_n, e_n]],
+  #
+  # it returns:
+  #
+  #   p_1**e_1 * p_2**e_2 * ... * p_n**e_n.
+  #
   # == Parameters
-  # +pd+:: Array of pairs of integers. The each internal
-  #        pair consists of a prime number -- a prime factor --
-  #        and a natural number -- an exponent.
+  # +pd+:: Array of pairs of integers.
+  #        Each pair consists of a prime number -- a prime factor --
+  #        and a natural number -- its exponent (multiplicity).
   #
   # == Example
-  # For <tt>[[p_1, e_1], [p_2, e_2], ...., [p_n, e_n]]</tt>, it returns:
+  #   Prime.int_from_prime_division([[3, 2], [5, 1]])  #=> 45
+  #   3**2 * 5                                         #=> 45
   #
-  #   p_1**e_1 * p_2**e_2 * .... * p_n**e_n.
-  #
-  #   Prime.int_from_prime_division([[2,2], [3,1]])  #=> 12
   def int_from_prime_division(pd)
     pd.inject(1){|value, (prime, index)|
       value * prime**index
@@ -193,27 +199,32 @@ def int_from_prime_division(pd)
 
   # Returns the factorization of +value+.
   #
+  # For an arbitrary integer:
+  #
+  #   p_1**e_1 * p_2**e_2 * ... * p_n**e_n,
+  #
+  # prime_division returns an array of pairs of integers:
+  #
+  #   [[p_1, e_1], [p_2, e_2], ..., [p_n, e_n]].
+  #
+  # Each pair consists of a prime number -- a prime factor --
+  # and a natural number -- its exponent (multiplicity).
+  #
   # == Parameters
   # +value+:: An arbitrary integer.
   # +generator+:: Optional. A pseudo-prime generator.
   #               +generator+.succ must return the next
-  #               pseudo-prime number in the ascending
-  #               order. It must generate all prime numbers,
-  #               but may also generate non prime numbers too.
+  #               pseudo-prime number in ascending order.
+  #               It must generate all prime numbers,
+  #               but may also generate non-prime numbers, too.
   #
   # === Exceptions
   # +ZeroDivisionError+:: when +value+ is zero.
   #
   # == Example
-  # For an arbitrary integer:
-  #
-  #   n = p_1**e_1 * p_2**e_2 * .... * p_n**e_n,
-  #
-  # prime_division(n) returns:
-  #
-  #   [[p_1, e_1], [p_2, e_2], ...., [p_n, e_n]].
   #
-  #   Prime.prime_division(12) #=> [[2,2], [3,1]]
+  #   Prime.prime_division(45)  #=> [[3, 2], [5, 1]]
+  #   3**2 * 5                  #=> 45
   #
   def prime_division(value, generator = Prime::Generator23.new)
     raise ZeroDivisionError if value == 0