factors: Give all exported members proper godoc

1 files changed, 59 insertions, 27 deletions

diff --git a/factors/score.go b/factors/score.go
index 00988c9..b1da963 100644
--- a/factors/score.go
+++ b/factors/score.go
@@ -5,21 +5,29 @@ import (
 	"math/big"
 )
 
-// Score returns a "factor score" equal to the sum of the reciprocoals
-// of the number n's factors.
-// Rationale:
-// A number's factors are one of the most important things that determines
-// how well it functions as a number base.  An easy way to determine how
-// good these factors are is to simply count them, but that comes with
-// the problem that all factors are considered equal when they really aren't
-// - divisibility by 2 (which ensures 1/2 is a terminating fraction and
-// you can tell whether a number is even or odd by looking at the last digit)
-// is more important than divisibility by 23.  The most obvious way of
-// accounting for this is by giving each factor a score and adding those
-// scores to get the overall score.  I chose score(f) = 1/f because it is
-// the simplest function that captures the intuition that smaller factors
-// are more valuable than larger ones.  It also gives the score a meaning:
-// a factor's score is the probability a random number is divisible by it.
+/*
+Score returns a "factor score" equal to the sum of the reciprocoals
+of the number n's factors.
+
+Rationale:
+A number's factors are one of the most important things that determines
+how well it functions as a number radix.  An easy way to determine how
+good these factors are is to simply count them, but that comes with
+the problem that all factors are considered equal when they really aren't
+- divisibility by 2 (which ensures 1/2 is a terminating fraction and
+you can tell whether a number is even or odd by looking at the last digit)
+is more important than divisibility by 23.  The most obvious way of
+accounting for this is by giving each factor a score and adding those
+scores to get the overall score.  I chose score(f) = 1/f because it is
+the simplest function that captures the intuition that smaller factors
+are more valuable than larger ones.  It also gives the score a meaning:
+a factor's score is the probability a random number is divisible by it.
+
+Special cases:
+
+	Score(0) = NaN
+	Score(1) = 1.0
+*/
 func Score(n uint) float64 {
 	if n == 0 {
 		return math.NaN()
@@ -54,30 +62,54 @@ func bigScore(n uint) float64 {
 	return score64
 }
 
-// BasicRank returns a rank describing how well a radix handles the simplest
-// fractions (1/2, 1/3, 1/4 and 1/5).  Zero and one are not true radices,
-// but because this rank otherwise only depends on a radix's remainder
-// mod 60, they have the same ranks as 60 and 61 (A+, F~).
-// Also known as 2345 Rank.
-func BasicRank(n uint) string {
+/*
+BasicRank returns a rank describing how well a radix handles the simplest
+fractions (1/2, 1/3, 1/4, 1/5).  It consists of two parts: a letter (A-F)
+and a sign (+, -, ~).  It is also known as the 2345 Rank.
+
+The letter determines how well the first three fractions are handled
+(specifically, what their decimal expansions look like):
+  - A means all three terminate with one digit.
+  - B means 1/2 and 1/3 terminate with one digit,
+    and 1/4 terminates with two digits.
+  - C means 1/2 and 1/4 terminate with one digit,
+    but 1/3 is infinitely repeating (pattern length 1-2 digits).
+  - D means 1/2 terminates with one digit,
+    but 1/3 is infinitely repeating (pattern length 1-2 digits),
+    and 1/4 terminates with two digits.
+  - E means 1/3 terminates with one digit,
+    but 1/2 and 1/4 are infinitely repeating
+    (pattern lengths 1 and 1-2 respectively).
+  - F means all three are infinitely repeating
+    (pattern lengths 1, 1-2 and 1-2 respectively).
+
+The sign determines how well 1/5 is handled:
+  - A plus means it terminates with one digit.
+  - A tilde means it repeats with a short (1-2 digit) pattern.
+  - A minus means it repeats with a long (4-digit) pattern.
+
+Because the rank only depends on radix % 60, 0 and 1 are given the same
+ranks as 60 and 61 (A+, F~).
+*/
+func BasicRank(radix uint) string {
 	var firstRank, secondRank string
 
 	switch uint(0) {
-	case n % 12:
+	case radix % 12:
 		firstRank = "A"
-	case n % 6:
+	case radix % 6:
 		firstRank = "B"
-	case n % 4:
+	case radix % 4:
 		firstRank = "C"
-	case n % 2:
+	case radix % 2:
 		firstRank = "D"
-	case n % 3:
+	case radix % 3:
 		firstRank = "E"
 	default:
 		firstRank = "F"
 	}
 
-	switch n % 5 {
+	switch radix % 5 {
 	case 0:
 		secondRank = "+"
 	case 1, 4: