docs(fun_ty.mli): Refine the documentation of fun_ty

Author: erikmd

src/ppx-metaquot/fun_ty.mli

@@ -62,19 +62,42 @@ val apply :
 
 (** GADT for function types.
 
-    Given an arrow type ['a -> 'row], the following construct provides
-    a more precise representation of this function type than
-    [[%ty: 'a -> 'row] : ('a -> 'row) Ty.ty]:
+    This abstract type fulfills a similar aim as the ['a Ty.ty] type:
+    provide a type-safe way to build terms representing an OCaml type
+    (relying on [Parsetree.core_type]), the type of these terms being
+    themselves parameterized by the type at stake, in order to
+    constrain the type of other arguments involved in the considered
+    (grader) expression.
 
-    [[%funty: 'a -> 'row] : (('a -> 'row) Ty.ty, 'a -> 'urow, 'ret) fun_ty]
+    For ['a Ty.ty], this aim can be achived with the ppx expression
+    [[%ty: int]], which builds an abstract term of type [int Ty.ty]
+    (this term also gathering an appropriate encoding of the [int]
+    type in terms of [Parsetree.core_type]).
 
-    In particular, the codomain type ['ret] is made explicit, so that
-    if ['row = 'b -> 'c], we get ['urow = 'b -> unit] and ['ret = 'c].
+    For implementing n-ary graders, this information is not sufficient
+    in practice, notably as we need to make it explicit in the type
+    annotation, what is the co-domain of the n-ary function at stake.
 
-    Usage: [arg_ty [%ty: int] @@ arg_ty [%ty: string] @@
-            last_ty [%ty: bool] [%ty: unit]]
+    This is achieved by the GADT
+    [(('ar -> 'row) Ty.ty, 'ar -> 'urow, 'ret) fun_ty].
 
-    Alternatively: [[%funty: int -> string -> bool -> unit]] *)
+    There are two ways to build terms of this type:
+
+    1. Use the two functions [arg_ty], [last_ty], and appropriate
+       [[%ty: type]] expressions, for example:
+
+        [arg_ty [%ty: int] @@
+         last_ty [%ty: string] [%ty: bool]];
+
+    2. Use directly the [[%funty: 'ar -> 'row]] construct, for example:
+
+        [[%funty: int -> string -> bool]].
+
+    For both cases in this example, we get a term of type:
+
+    [((int -> string -> bool) Ty.ty, int -> string -> unit, bool) fun_ty],
+
+    where the co-domain type [bool] is now explicit. *)
 type ('arrow, 'uarrow, 'ret) fun_ty
 
 (** [last_ty [%ty: a] [%ty: r]] builds a function type for [a -> r] *)