Improve docs for Prime.{prime_division,int_from_prime_division} (#8)

Move explanation for the decomposition array from the Example section
to the method description. Mention the term "multiplicity".

Use examples that also demonstrate factors with multiplicity
other than 1, and avoid factors/multiplicities with the same value.
Also add the decomposition written as simple mathematical expression.

This also fixes missing syntax highlighting for the code examples
due to verbatim blocks that did not only include Ruby code.

1 files changed, 29 insertions, 18 deletions

diff --git a/lib/prime.rb b/lib/prime.rb
index 113af9f702..d2de8dc017 100644
--- a/lib/prime.rb
+++ b/lib/prime.rb
@@ -174,17 +174,23 @@ class Prime
 
   # 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 @@ class Prime
 
   # 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