Improve the comments.

diff --git a/deal.c b/deal.c
index 09cbd9ac2642359e6a7d3363bbc0b119b4e5e41c..bc427a923f64e8710a7a5c024397bc0025d473e6 100644 (file)
--- a/deal.c
+++ b/deal.c
@@ -1,3 +1,31 @@
+/*
+ * cardprobs -- compute combination probabilities for Magic: The Gathering
+ *
+ * by Jeremy C. York <jeremy@stat.cmu.edu>; cleanup, comments, and
+ * interface improvements by Eric Raymond <esr@snark.thyrsus.com>.
+ *
+ * If I have M special cards (for example, land cards) in my deck, and N
+ * total cards in my deck, and I draw k cards from that deck (*without
+ * replacement* -- the fact that you don't put them back into the deck
+ * can be important for some values of M and N), and if X counts the
+ * number of special cards contained in those k drawn cards...
+ * 
+ * Then X has a hypergeometric distribution, with the following formula
+ * for probabilities:
+ * 
+ *                 B(M, i) * B(N-M, k-i)
+ *      P(X = i) = ---------------------
+ *                   B(N, k)
+ * 
+ * where B(a,b) is read "a choose b", and is the number of ways
+ * to choose b objects out of a possible objects.  The formula for it is
+ * 
+ *     B(a,b)  =   a!/(b! (a-b)!)
+ *
+ * Compile with:
+ *
+ *     cc cardprobs.c -lm -o cardprobs
+ */
 #include <math.h>
 
 #define BASEHAND       7       /* # cards in initial deal */
@@ -58,6 +86,12 @@ main(argc, argv)
     }
 }
 
+/* 
+ * We avoid nasty numerical problems by using log of gamma function to
+ * calculate factorials, and doing everything on the log scale before
+ * giving the final answer.
+ */
+
 double hyper_prob(x, k, M, N)
     int x, k, M, N;
 {