Merge pull request #336 from jmid/add-corner-warning

Documentation: Add notes to corner-case generators and fix some broken documentation references

Author: jmid

CHANGELOG.md

@@ -8,6 +8,8 @@
   workaround MinGW float printing to also pass expect tests
 - Fix dune snippets missing a language specifier in README.adoc
   causing `asciidoc` to error
+- Add a note to `QCheck{,2.Gen}.small_int_corners` and `QCheck{,2}.Gen.graft_corners`
+  about internal state, and fix a range of documentation reference warnings
 
 ## 0.24
 

doc/qcheck-core/index.mld

@@ -5,7 +5,7 @@ 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}
+{1 The [qcheck-core] library}
 
 The [qcheck-core] library exposes two toplevel modules:
 
@@ -21,7 +21,7 @@ removing the need for having to hand-write shrinkers.
 file an issue if you encounter problems using either of the two
 modules.
 
-{1: The [qcheck-core.runner] library}
+{1 The [qcheck-core.runner] library}
 
 The entry point of the [qcheck-core.runner] library is the {!QCheck_base_runner} module.
 

src/core/QCheck.mli

@@ -78,7 +78,7 @@ all rights reserved.
     ]}
 
     More complex and powerful combinators can be found in Gabriel Scherer's
-    {!Generator} module. Its documentation can be found
+    {{:https://github.com/gasche/random-generator}[Generator]} module. Its documentation can be found
     {{:http://gasche.github.io/random-generator/doc/Generator.html } here}.
 *)
 
@@ -325,6 +325,12 @@ module Gen : sig
   val graft_corners : 'a t -> 'a list -> unit -> 'a t
   (** [graft_corners gen l ()] makes a new generator that enumerates
       the corner cases in [l] and then behaves like [g].
+
+      Note that [graft_corners gen l ()] is stateful, meaning that once the
+      elements of [l] have been emitted, subsequent calls will not reproduce
+      them. It is therefore recommended that separate tests each use a fresh
+      generator.
+
       @since 0.6 *)
 
   val int_pos_corners : int list
@@ -415,7 +421,7 @@ module Gen : sig
   val bytes : ?gen:char t -> bytes t
   (** Builds a bytes generator. Bytes size is generated by {!nat}.
       Accepts an optional character generator (the default is {!char}).
-      See also {!bytes_of} and {!bytes_readable} for versions without
+      See also {!bytes_of} and {!bytes_printable} for versions without
       optional parameters.
       @since 0.20 *)
 
@@ -640,7 +646,7 @@ module Gen : sig
   (** {{: https://ocaml.org/manual/bindingops.html} Binding operator} alias for {!pair}. *)
 
   val ( let* ) : 'a t -> ('a -> 'b t) -> 'b t
-  (** {{: https://ocaml.org/manual/bindingops.html} Binding operator} alias for {!bind}. *)
+  (** {{: https://ocaml.org/manual/bindingops.html} Binding operator} alias for {!(>>=)}. *)
 
   val ( and* ) : 'a t -> 'b t -> ('a * 'b) t
   (** {{: https://ocaml.org/manual/bindingops.html} Binding operator} alias for {!pair}. *)
@@ -1144,7 +1150,18 @@ val pos_int : int arbitrary
 
 val small_int_corners : unit -> int arbitrary
 (** As [small_int], but each newly created generator starts with
-    a list of corner cases before falling back on random generation. *)
+    a list of corner cases before falling back on random generation.
+
+    Note that [small_int_corners ()] is stateful, meaning that once the list of
+    corner cases has been emitted, subsequent calls will not reproduce them.
+    As a consequence, in the following example, the first test fails with a
+    counter example, whereas the second rerun does not:
+    {[
+      let gen = QCheck.small_int_corners ()
+      let t = QCheck.Test.make ~name:"never max_int" gen (fun i -> i <> max_int)
+      let _ = QCheck_base_runner.run_tests ~verbose:true [t;t]
+    ]}
+ *)
 
 val neg_int : int arbitrary
 (** Negative int generator (0 included, see {!Gen.neg_int}).
@@ -1400,7 +1417,7 @@ val tup9 :
 
 val choose : 'a arbitrary list -> 'a arbitrary
 (** Choose among the given list of generators. The list must not
-    be empty; if it is Invalid_argument is raised. *)
+    be empty; if it is [Invalid_argument] is raised. *)
 
 val oneofl : ?print:'a Print.t -> ?collect:('a -> string) ->
   'a list -> 'a arbitrary
@@ -1878,7 +1895,7 @@ module Tuple : sig
   val nil : unit t
   val cons : 'a -> 'b t -> ('a * 'b) t
 
-  (** How to observe a  {!'a t} *)
+  (** How to observe a  {{!t}['a t]} *)
   type 'a obs
 
   val o_nil : unit obs
@@ -1889,7 +1906,7 @@ module Tuple : sig
     (** Alias to {!cons}. *)
 
     val (@->) : 'a Observable.t -> 'b obs -> ('a * 'b) obs
-    (** Alias to {!B_cons}. *)
+    (** Alias to {!o_cons}. *)
   end
 
   include module type of Infix

src/core/QCheck2.mli

@@ -34,7 +34,7 @@ content will appear. *)
 
     {1 Examples}
 
-    - "{!List.rev} is involutive" (the test passes so [check_exn] returns [()]):
+    - "[List.rev] is involutive" (the test passes so [check_exn] returns [()]):
 
     {[
       let test =
@@ -233,8 +233,18 @@ module Gen : sig
 
   val small_int_corners : unit -> int t
   (** As {!small_int}, but each newly created generator starts with
-    a list of corner cases before falling back on random generation. *)
+    a list of corner cases before falling back on random generation.
 
+    Note that [small_int_corners ()] is stateful, meaning that once the list of
+    corner cases has been emitted, subsequent calls will not reproduce them.
+    As a consequence, in the following example, the first test fails with a
+    counter example, whereas the second rerun does not:
+    {[
+      let gen = QCheck2.Gen.small_int_corners ()
+      let t = QCheck2.Test.make ~name:"never max_int" gen (fun i -> i <> max_int)
+      let _ = QCheck_base_runner.run_tests ~verbose:true [t;t]
+    ]}
+  *)
 
   val int32 : int32 t
   (** Generates uniform {!int32} values.
@@ -417,7 +427,7 @@ module Gen : sig
 
   val make_primitive : gen : (Random.State.t -> 'a) -> shrink : ('a -> 'a Seq.t) -> 'a t
   (** [make_primitive ~gen ~shrink] creates a generator from a function [gen] that creates
-      a random value (this function must only use the given {!Random.State.t} for randomness)
+      a random value (this function must only use the given [Random.State.t] for randomness)
       and a function [shrink] that, given a value [a], returns a lazy list of
       "smaller" values (used when a test fails).
 
@@ -624,6 +634,11 @@ module Gen : sig
       Does not shrink if the test fails on a grafted value.
       Shrinks towards [gen] otherwise.
 
+      Note that [graft_corners gen l ()] is stateful, meaning that once the
+      elements of [l] have been emitted, subsequent calls will not reproduce
+      them. It is therefore recommended that separate tests each use a fresh
+      generator.
+
       @since 0.6 *)
 
   val int_pos_corners : int list
@@ -691,7 +706,7 @@ module Gen : sig
   val option : ?ratio:float -> 'a t -> 'a option t
   (** [option gen] is an [option] generator that uses [gen] when generating [Some] values.
 
-      Shrinks towards {!None} then towards shrinks of [gen].
+      Shrinks towards [None] then towards shrinks of [gen].
 
       @param ratio a float between [0.] and [1.] indicating the probability of a sample to be [Some _]
       rather than [None] (value is [0.85]).
@@ -782,7 +797,7 @@ module Gen : sig
   val flatten_opt : 'a t option -> 'a option t
   (** Generate an option from an optional generator.
 
-      Shrinks towards {!None} then shrinks on the value.
+      Shrinks towards [None] then shrinks on the value.
 
       @since 0.13 *)
 
@@ -1272,16 +1287,16 @@ module Shrink : sig
   *)
 
   val int_towards : int -> int -> int Seq.t
-  (** {!number_towards} specialized to {!int}. *)
+  (** {!number_towards} specialized to [int]. *)
 
   val int32_towards : int32 -> int32 -> int32 Seq.t
-  (** {!number_towards} specialized to {!int32}. *)
+  (** {!number_towards} specialized to [int32]. *)
 
   val int64_towards : int64 -> int64 -> int64 Seq.t
-  (** {!number_towards} specialized to {!int64}. *)
+  (** {!number_towards} specialized to [int64]. *)
 
   val float_towards : float -> float -> float Seq.t
-  (** {!number_towards} specialized to {!float}.
+  (** {!number_towards} specialized to [float].
 
       There are various ways to shrink a float:
       - try removing floating digits, i.e. towards integer values
@@ -2027,8 +2042,8 @@ val find_example_gen :
     Below are the most common situations you may encounter:
     - as shrinking is now integrated, several function arguments like [~shrink] or [~rev] have been removed: you
       can remove such reverse functions, they will no longer be necessary.
-    - accessor functions like {!QCheck.gen} have been renamed to consistent names like {!get_gen}.
-    - {!QCheck.map_keep_input} has been removed: you can use {!map} directly.
+    - accessor functions like {!val:QCheck.gen} have been renamed to consistent names like {!Test.get_gen}.
+    - {!QCheck.map_keep_input} has been removed: you can use {!Gen.map} directly.
     - {!Gen.t} is no longer public, it is now abstract: it is recommended to use
       {{!section:Gen.composing_generators} generator composition} to make generators. {!Gen.make_primitive}
       was added to create generators with finer control (in particular of shrinking).

src/ppx_deriving_qcheck/QCheck_generators.ml

@@ -3,7 +3,7 @@ open Ppxlib
 (** This module contains all generators from QCheck used to
     derive a type declaration *)
 
-(** {2. Version} *)
+(** {2 Version} *)
 
 type version = [`QCheck | `QCheck2]
 
@@ -28,11 +28,11 @@ let apply3 loc f a b c  = [%expr [%e f] [%e a] [%e b] [%e c]]
 
 let apply4 loc f a b c d = [%expr [%e f] [%e a] [%e b] [%e c] [%e d]]
 
-(** {2. Type} *)
+(** {2 Type} *)
 
 let ty version = Ldot (Ldot (Lident (to_module version), "Gen"), "t")
 
-(** {2. Primitive generators} *)
+(** {2 Primitive generators} *)
 
 let unit loc version = with_prefix_gen loc version "unit"
 
@@ -62,7 +62,7 @@ let array ~loc ~version e =
   let gen = with_prefix_gen loc version "array" in
   apply1 loc gen e
 
-(** {2. Generator combinators} *)
+(** {2 Generator combinators} *)
 
 let pure ~loc ~version e =
   let gen = with_prefix_gen loc version "pure" in
@@ -101,7 +101,7 @@ let fix ~loc ~version e =
 
 (** Observable generators *)
 module Observable = struct
-  (** {2. Primitive generators} *)
+  (** {2 Primitive generators} *)
   let unit loc version = with_prefix_obs loc version "unit"
 
   let int loc version = with_prefix_obs loc version "int"
@@ -130,7 +130,7 @@ module Observable = struct
     let obs = with_prefix_obs loc version "array" in
     apply1 loc obs e
 
-  (** {2. Observable combinators} *)
+  (** {2 Observable combinators} *)
   let pair ~loc ~version a b =
     let obs = with_prefix_obs loc version "pair" in
     apply2 loc obs a b

src/ppx_deriving_qcheck/tuple.ml

@@ -2,7 +2,7 @@ open Ppxlib
 module G = QCheck_generators
 module O = G.Observable
 
-(** {1. Tuple } *)
+(** {1 Tuple } *)
 
 (** This module implements nested tuples based on QCheck tuples generators (or observables):
     - [Gen.pair]

src/runner/QCheck_base_runner.mli

@@ -25,7 +25,7 @@ all rights reserved.
     will be 0 if all tests pass, 1 otherwise.
 
     {!run_tests_main} can be used as a shortcut for that, also
-    featuring command-line parsing (using {!Arg}) to activate
+    featuring command-line parsing (using [Arg]) to activate
     verbose mode and others.
 *)