Better explanations

README.textile

@@ -372,7 +372,12 @@ For example a <code>String</code> is shrinkable until it is empty (e.g. <code>""
 "".shrinkable?        # => false
 </code></pre>
 
-Shrinking allows <code>Property#check</code> to find a reduced value that still fails the condition. The value is not truely minimal as we do not perform a complete in-depth traversal of the failure tree, but is usually reduced enough to start debugging.
+Shrinking allows <code>Property#check</code> to find a reduced value that still fails the condition. The value is not truely minimal because:
+
+* we do not perform a complete in-depth traversal of the failure tree
+* we limit the search to a maximum 1024 shrinking operations
+
+but is usually reduced enough to start debugging.
 
 Enable shrinking with
 
@@ -381,7 +386,9 @@ require 'rantly/shrinks'
 </code></pre>
 
 Use <code>Tuple</code> class if you want an array whose elements are individually shrinked, but are not removed.
-Use <code>Static</code> class if you want an array with no shrinking at all.
+Use <code>Deflating</code> class if you want an array whose elements are individully shrinked whenever possible, and removed otherwise.
+
+Normal arrays or hashes are not shrinked.
 
 
 h1. Copyright

examples/00-even-numbers/README

@@ -3,15 +3,24 @@ HOW TO RUN
   $ cd examples/00-even-numbers
   $ rspec spec/tests.rb
 
+
 WHAT IT DOES
 
   It creates an array of random small numbers.
   It then verifies they are all even (which they are not, of course).
+  Rantly then shrinks that sample of data to a smaller failing set.
+
 
 EXTERNAL TESTED PROGRAM
 
   None, everything is in the test.
 
+
+INTERNAL MODEL
+
+  None, the random data are tested directly.
+
+
 USED CLASSES
 
   Integer:   standard Ruby integer

examples/01-circular_buffer/README

@@ -4,13 +4,20 @@ HOW TO RUN
   $ gcc -o circular_buffer circular_buffer_bugged.c
   $ rspec tests/tests.rb
 
+
 WHAT IT DOES
 
   This example takes its inspiration from the must-see video
 
     https://www.youtube.com/watch?v=zi0rHwfiX1Q
     John Hughes - Testing the Hard Stuff and Staying Sane
 
+  It makes sure whether an external program managing a
+  circular buffer behaves properly. If not, Rantly tries to reduce
+  the two parameters, the sequence of operations and the size
+  of the buffer, to a minimal failing sample.
+
+
 EXTERNAL TESTED PROGRAM
 
    circular_buffer_bugged.c tries to implement a queue of integers
@@ -20,13 +27,21 @@ EXTERNAL TESTED PROGRAM
    circular_buffer.c is the fixed version that applies the old trick
    of allocating one more element in the buffer than we want to use.
 
-USED CLASSES:
 
-  Integer:   standard Ruby integer
-  Operation: modelize one of three operations put(value), get() or size();
-             we could simply have used a symbol, but this convenience class
-             enables to pretty-print
+INTERNAL MODEL
+
+   The circular buffer managed by the external program
+   is modelized internally with a simple Ruby array.
+
+
+USED CLASSES
+
+  Operation: represents one of three operations put(value), get() or size();
+             we could have simply used an array with a symbol (the operation)
+             and an integer (the parameter), but this convenience class
+             enables to print the operation in a nicer looking way
   Deflating: deflating array (here: of operations)
-  Tuple:     array of shrinking values values
-             (here: two elements, the operations and the size of the queue)
+  Integer:   standard Ruby integer (here: the size of the circular buffer)
+  Tuple:     array of shrinking values
+             (here: two elements, the operations and the size of the buffer)