From 8788ff6c839318c8876e89888c95297dd7784ee7 Mon Sep 17 00:00:00 2001
From: Richard Eisenberg <reisenberg@janestreet.com>
Date: Tue, 1 Nov 2022 17:24:29 -0400
Subject: [PATCH] Add/move some documentation

---
 parsing/location.mli | 17 +++++++++++++++++
 parsing/parser.mly   | 18 +-----------------
 typing/typeopt.ml    | 10 ++++++++--
 3 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/parsing/location.mli b/parsing/location.mli
index 5ba80b04daf..faad4a5de86 100644
--- a/parsing/location.mli
+++ b/parsing/location.mli
@@ -22,6 +22,23 @@
 
 open Format
 
+(* loc_ghost: Ghost expressions and patterns:
+  expressions and patterns that do not appear explicitly in the
+  source file they have the loc_ghost flag set to true.
+  Then the profiler will not try to instrument them and the
+  -annot option will not try to display their type.
+
+  Every grammar rule that generates an element with a location must
+  make at most one non-ghost element, the topmost one.
+
+  How to tell whether your location must be ghost:
+  A location corresponds to a range of characters in the source file.
+  If the location contains a piece of code that is syntactically
+  valid (according to the documentation), and corresponds to the
+  AST node, then the location must be real; in all other cases,
+  it must be ghost.
+*)
+
 type t = Warnings.loc = {
   loc_start: Lexing.position;
   loc_end: Lexing.position;
diff --git a/parsing/parser.mly b/parsing/parser.mly
index c338eef3249..42307f41f9d 100644
--- a/parsing/parser.mly
+++ b/parsing/parser.mly
@@ -115,23 +115,7 @@ let mkoperator =
 let mkpatvar ~loc name =
   mkpat ~loc (Ppat_var (mkrhs name loc))
 
-(*
-  Ghost expressions and patterns:
-  expressions and patterns that do not appear explicitly in the
-  source file they have the loc_ghost flag set to true.
-  Then the profiler will not try to instrument them and the
-  -annot option will not try to display their type.
-
-  Every grammar rule that generates an element with a location must
-  make at most one non-ghost element, the topmost one.
-
-  How to tell whether your location must be ghost:
-  A location corresponds to a range of characters in the source file.
-  If the location contains a piece of code that is syntactically
-  valid (according to the documentation), and corresponds to the
-  AST node, then the location must be real; in all other cases,
-  it must be ghost.
-*)
+(* See commentary about ghost locations at the declaration of Location.t *)
 let ghexp ~loc d = Exp.mk ~loc:(ghost_loc loc) d
 let ghpat ~loc d = Pat.mk ~loc:(ghost_loc loc) d
 let ghtyp ~loc d = Typ.mk ~loc:(ghost_loc loc) d
diff --git a/typing/typeopt.ml b/typing/typeopt.ml
index 31c36a9b003..ac2ef4cedb5 100644
--- a/typing/typeopt.ml
+++ b/typing/typeopt.ml
@@ -21,6 +21,9 @@ open Asttypes
 open Typedtree
 open Lambda
 
+(* Expand a type, looking through ordinary synonyms, private synonyms,
+   links, and [@@unboxed] types. The returned type will be therefore be none
+   of these cases. *)
 let scrape_ty env ty =
   match get_desc ty with
   | Tconstr _ ->
@@ -42,6 +45,7 @@ let scrape_ty env ty =
       end
   | _ -> ty
 
+(* See [scrape_ty]; this returns the [type_desc] of a scraped [type_expr]. *)
 let scrape env ty =
   get_desc (scrape_ty env ty)
 
@@ -77,13 +81,15 @@ let maybe_pointer_type env ty =
 let maybe_pointer exp = maybe_pointer_type exp.exp_env exp.exp_type
 
 type classification =
-  | Int
+  | Int   (* any immediate type *)
   | Float
   | Lazy
   | Addr  (* anything except a float or a lazy *)
   | Any
 
-let classify env ty =
+(* Classify a ty into a [classification]. Looks through synonyms, using [scrape_ty].
+   Returning [Any] is safe, though may skip some optimizations. *)
+let classify env ty : classification =
   let ty = scrape_ty env ty in
   if maybe_pointer_type env ty = Immediate then Int
   else match get_desc ty with