Merge pull request #302 from jmid/doc-polish

Documentation polish

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## NEXT RELEASE
 
+- Clean-up `QCheck` and `QCheck2` documentation pages
 - Add `exponential` generator to `QCheck`, `QCheck.Gen`, and `QCheck2.Gen`
 - Add `Shrink.bool` and use it in `QCheck.bool`
 - Remove unread `fun_gen` field from `QCheck2`'s `fun_repr_tbl` type

Makefile

@@ -11,7 +11,7 @@ clean:
 	@dune clean
 
 doc:
-	@dune build @doc
+	@dune build @doc doc/
 
 example-test:
 	@dune exec example/ounit/QCheck_test.exe

doc/dune

@@ -0,0 +1,3 @@
+(documentation
+  (package qcheck-core)
+  (mld_files index))

doc/index.mld

@@ -0,0 +1,31 @@
+{0 qcheck-core}
+
+The [qcheck-core] opam package contains two libraries:
+
+- The [qcheck-core] library for defining property-based tests
+- The [qcheck-core.runner] library for running property-based tests
+
+{1: The [qcheck-core] library}
+
+The [qcheck-core] library exposes two toplevel modules:
+
+- {!QCheck} is the initial property-based-testing module and
+- {!QCheck2} is a newer property-based-testing module supporting integrated shrinking
+
+Of the two, {!QCheck} is the most battle-tested module.
+{!QCheck2} on the other hand offers integrated shrinking, thus
+removing the need for having to hand-write shrinkers.
+
+{!QCheck} tests can be ported to {!QCheck2} by following the
+{{!QCheck2.migration_qcheck2}migration guide}. Please
+file an issue if you encounter problems using either of the two
+modules.
+
+{1: The [qcheck-core.runner] library}
+
+The entry point of the [qcheck-core.runner] library is the {!QCheck_base_runner} module.
+
+One can run a list of property-based tests by calling either
+
+- {!QCheck_base_runner.run_tests}, which accepts a number of optional arguments, or
+- {!QCheck_base_runner.run_tests_main}, which can be controlled via command-line arguments

src/core/QCheck.ml

@@ -1042,9 +1042,9 @@ type 'a stat = string * ('a -> int)
 
 type 'a arbitrary = {
   gen: 'a Gen.t;
-  print: ('a -> string) option; (** print values *)
+  print: ('a Print.t) option; (** print values *)
   small: ('a -> int) option;  (** size of example *)
-  shrink: ('a -> 'a Iter.t) option;  (** shrink to smaller examples *)
+  shrink: ('a Shrink.t) option;  (** shrink to smaller examples *)
   collect: ('a -> string) option;  (** map value to tag, and group by tag *)
   stats: 'a stat list; (** statistics to collect and print *)
 }