X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FSub-Nary.git;a=blobdiff_plain;f=README;h=98287098967c5503ce4f6fbab02d356b8de5bda2;hp=9f80bb02e0daf5b5921e22a550bd90c19012c77b;hb=HEAD;hpb=4b846088d0ffe4f979b145ec2af821922bd5c7af

diff --git a/README b/README
index 9f80bb0..9828709 100644
--- a/README
+++ b/README
@@ -3,7 +3,7 @@ NAME
     list context.
 
 VERSION
-    Version 0.01
+    Version 0.03
 
 SYNOPSIS
         use Sub::Nary;
@@ -22,7 +22,7 @@ METHODS
   "new"
     The usual constructor. Currently takes no argument.
 
-  "nary $coderf"
+  "nary $coderef"
     Takes a code reference to a named or anonymous subroutine, and returns a
     hash reference whose keys are the possible numbers of returning scalars,
     and the corresponding values the "probability" to get them. The special
@@ -41,8 +41,7 @@ METHODS
 PROBABILITY OF RETURN
     The probability is computed as such :
 
-    * All the returning points in the same subroutine (i.e. all the explicit
-    "return" and the last computed value) are considered equally possible.
+    * When branching, each branch is considered equally possible.
         For example, the subroutine
 
             sub simple {
@@ -65,10 +64,10 @@ PROBABILITY OF RETURN
              }
             }
 
-        it is considered to return 1 (when the two tests fail, the last
-        computed value is returned, which here is "$x > 0.9" evaluated in
-        the scalar context of the test), 2 or 3 arguments each with
-        probability "1/3".
+        it is considered to return 3 scalars with probability "1/2", 2 with
+        probability "1/2 * 1/2 = 1/4" and 1 (when the two tests fail, the
+        last computed value is returned, which here is "$x > 0.9" evaluated
+        in the scalar context of the test) with remaining probability "1/4".
 
     * The total probability law for a given returning point is the
     convolution product of the probabilities of its list elements.
@@ -88,7 +87,12 @@ PROBABILITY OF RETURN
         1/4", 3 with probability "1/2 * 1/2 + 1/2 * 1/2 = 1/2" and 4 with
         probability "1/4" too.
 
-    * The 'list' state is absorbant in regard of all the other ones.
+    * If a core function may return different numbers of scalars, each kind
+    is considered equally possible.
+        For example, "stat" returns 13 elements on success and 0 on error.
+        The according probability will then be "{ 0 => 0.5, 13 => 0.5 }".
+
+    * The "list" state is absorbing in regard of all the other ones.
         This is just a pedantic way to say that "list + fixed length =
         list". That's why
 
@@ -96,9 +100,10 @@ PROBABILITY OF RETURN
              return 1, simple(), @_
             }
 
-        is considered as always returning an unbounded list. The convolution
-        law also does not behave the same when "list" elements are involved
-        : in the following example,
+        is considered as always returning an unbounded list.
+
+        Also, the convolution law does not behave the same when "list"
+        elements are involved : in the following example,
 
             sub oneorlist {
              if (rand < 0.1) {
@@ -128,8 +133,8 @@ CAVEATS
 DEPENDENCIES
     perl 5.8.1.
 
-    Carp (standard since perl 5), B (since perl 5.005), XSLoader (since perl
-    5.006) and List::Util (since perl 5.007003).
+    Carp (standard since perl 5), B (since perl 5.005) and XSLoader (since
+    perl 5.006).
 
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.