Clarify Quantification usage and functions

quickcheck-dynamic/src/Test/QuickCheck/DynamicLogic/Quantify.hs

@@ -32,12 +32,21 @@ import Test.QuickCheck
 import Test.QuickCheck.DynamicLogic.CanGenerate
 import Test.QuickCheck.StateModel
 
--- | A `Quantification` over a type @a@ is a generator that can be used with
---   `Plutus.Contract.Test.ContractModel.forAllQ` to generate random values in
---   DL scenarios. In addition to a QuickCheck generator a `Quantification` contains a shrinking
---   strategy that ensures that shrunk values stay in the range of the generator.
+-- | A `Quantification` over a type @a@ is a generator that can be used to generate random values in
+-- DL scenarios.
+--
+-- A `Quantification` is similar to a  `Test.QuickCheck.Arbitrary`, it groups together:
+--
+-- * A standard QuickCheck _generator_ in the `Gen` monad,
+-- * A _shrinking_ strategy for generated values in the case of a
+--   failures ensuring they stay within the domain,
+-- * A _predicate_ allowing finer grained control on generation
+--   and shrinking process, e.g in the case the range of the generator
+--   depends on trace context.
 data Quantification a = Quantification
-  { genQ :: Maybe (Gen a)
+  { -- FIXME: why is this a Maybe? It makes things annoying down the road, smells like
+    -- something which would benefit from better typing?
+    genQ :: Maybe (Gen a)
   , isaQ :: a -> Bool
   , shrQ :: a -> [a]
   }
@@ -51,10 +60,9 @@ generateQ q = fromJust (genQ q) `suchThat` isaQ q
 shrinkQ :: Quantification a -> a -> [a]
 shrinkQ q a = filter (isaQ q) (shrQ q a)
 
--- | Wrap a `Gen a` generator in a `Quantification a`.
--- Uses given shrinker.
-withGenQ :: Gen a -> (a -> [a]) -> Quantification a
-withGenQ gen = Quantification (Just gen) (const True)
+-- | Construct a `Quantification a` from its constituents.
+withGenQ :: Gen a -> (a -> Bool) -> (a -> [a]) -> Quantification a
+withGenQ gen = Quantification (Just gen)
 
 -- | Pack up an `Arbitrary` instance as a `Quantification`. Treats all values as being in range.
 arbitraryQ :: Arbitrary a => Quantification a