Incorporate feedback for comments

hypothesis-python/src/hypothesis/internal/conjecture/data.py

@@ -46,11 +46,13 @@ class Example(object):
     """Examples track the hierarchical structure of draws from the byte stream,
     within a single test run.
 
-    An example usually corresponds to a single draw from a strategy, and
-    includes that strategy's nested draws as children. There are also other
-    kinds of examples, such as leaf examples that correspond to individual
-    low-level blocks, and a single top-level example that spans the entire
-    input.
+    Examples are created to mark regions of the byte stream that might be
+    useful to the shrinker, such as:
+    - The bytes used by a single draw from a strategy.
+    - Useful groupings within a strategy, such as individual list elements.
+    - Strategy-like helper functions that aren't first-class strategies.
+    - Each lowest-level draw of bits or bytes from the byte stream.
+    - A single top-level example that spans the entire input.
 
     Example-tracking allows the shrinker to try "high-level" transformations,
     such as rearranging or deleting the elements of a list, without having
@@ -77,9 +79,10 @@ class Example(object):
     # we see a byte that is neither forced nor zero.
     trivial = attr.ib(default=True)
 
-    # True if this example can be discarded by the shrinker, without affecting
-    # the value produced by the enclosing example. Typically set when a
-    # rejection sampler decides to reject a generated value and try again.
+    # True if we believe that the shrinker should be able to delete this
+    # example completely, without affecting the value produced by its enclosing
+    # strategy. Typically set when a rejection sampler decides to reject a
+    # generated value and try again.
     discarded = attr.ib(default=None)
 
     # List of child examples, represented as indices into the example list.
@@ -96,8 +99,8 @@ class Block(object):
     within a single test run.
 
     Block-tracking allows the shrinker to try "low-level"
-    transformations, such as minimizing the numeric value of individual
-    blocks, or of pairs of blocks.
+    transformations, such as minimizing the numeric value of an
+    individual call to ``draw_bits``.
     """
 
     start = attr.ib()
@@ -106,9 +109,9 @@ class Block(object):
     # Index of this block inside the overall list of blocks.
     index = attr.ib()
 
-    # True if this block's byte values were forced by a write operation, and
-    # were not read from the input stream. Modifying those byte values in the
-    # shrinker is unlikely to be useful.
+    # True if this block's byte values were forced by a write operation.
+    # As long as the bytes before this block remain the same, modifying this
+    # block's bytes will have no effect.
     forced = attr.ib()
 
     # True if this block's byte values are all 0. Reading this flag can be