https://git.ruby-lang.org/ruby.git/commit/?id=baaf681570

From baaf6815704ef36160e45244b844b633ed51c3b4 Mon Sep 17 00:00:00 2001
From: Marcus Stollsteimer <sto.mar@w...>
Date: Fri, 27 Dec 2019 20:19:37 +0100
Subject: 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.

diff --git a/lib/prime.rb b/lib/prime.rb
index 113af9f..d2de8dc 100644
--- a/lib/prime.rb
+++ b/lib/prime.rb
@@ -174,17 +174,23 @@ class Prime https://github.com/ruby/ruby/blob/trunk/lib/prime.rb#L174
 
   # 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 https://github.com/ruby/ruby/blob/trunk/lib/prime.rb#L199
 
   # 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
-- 
cgit v0.10.2


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/