Comments from Antal

ocaml/parsing/ast_helper.ml

@@ -108,8 +108,10 @@ module Typ = struct
             Ptyp_object (List.map loop_object_field lst, o)
         | Ptyp_class (longident, lst) ->
             Ptyp_class (longident, List.map loop lst)
-        (* A Ptyp_alias might be a layout annotation, but the code here
-           still has the correct behavior. *)
+        (* A Ptyp_alias might be a layout annotation (that is, it might have
+           attributes which mean it should be interpreted as a
+           Jane_syntax.Layouts.Ltyp_alias), but the code here still has the
+           correct behavior. *)
         | Ptyp_alias(core_type, string) ->
             check_variable var_names t.ptyp_loc string;
             Ptyp_alias(loop core_type, string)

ocaml/parsing/ast_iterator.ml

@@ -91,7 +91,7 @@ let iter_tuple3 f1 f2 f3 (x, y, z) = f1 x; f2 y; f3 z
 let iter_opt f = function None -> () | Some x -> f x
 
 let iter_loc sub {loc; txt = _} = sub.location sub loc
-let iter_loc2 sub f { loc; txt } =
+let iter_loc_txt sub f { loc; txt } =
   sub.location sub loc;
   f sub txt
 
@@ -121,7 +121,7 @@ module T = struct
     | Oinherit t -> sub.typ sub t
 
   let layout_annotation sub =
-    iter_loc2 sub sub.layout_annotation
+    iter_loc_txt sub sub.layout_annotation
 
   let type_vars_layouts sub (tvls : type_vars_layouts) =
     List.iter (iter_opt (layout_annotation sub)) tvls
@@ -132,13 +132,13 @@ module T = struct
 
   let iter_jst_layout sub : Jane_syntax.Layouts.core_type -> _ = function
     | Ltyp_var { name = _; layout } ->
-      iter_loc2 sub sub.layout_annotation layout
+      iter_loc_txt sub sub.layout_annotation layout
     | Ltyp_poly { bound_vars; inner_type } ->
       List.iter (bound_var sub) bound_vars;
       sub.typ sub inner_type
     | Ltyp_alias { aliased_type; name = _; layout } ->
       sub.typ sub aliased_type;
-      iter_loc2 sub sub.layout_annotation layout
+      iter_loc_txt sub sub.layout_annotation layout
 
   let iter_jst sub : Jane_syntax.Core_type.t -> _ = function
     | Jtyp_layout typ -> iter_jst_layout sub typ
@@ -537,7 +537,7 @@ module E = struct
         sub.expr sub e; iter_opt (sub.typ sub) t
     | Pexp_object cls -> sub.class_structure sub cls
     | Pexp_newtype (_s, e, l) ->
-        iter_opt (iter_loc2 sub sub.layout_annotation) l;
+        iter_opt (iter_loc_txt sub sub.layout_annotation) l;
         sub.expr sub e
     | Pexp_pack me -> sub.module_expr sub me
     | Pexp_open (o, e) ->

ocaml/parsing/jane_syntax_parsing.ml

@@ -558,7 +558,7 @@ module Make_with_attribute
     let desc ast : _ With_attributes.t =
       { desc = desc ast; jane_syntax_attributes = attributes ast }
 
-    let make_jane_syntax name ?payload ast : _ With_attributes.t =
+    let make_jane_syntax name ?(payload = PStr []) ast : _ With_attributes.t =
       let { With_attributes.desc
           ; jane_syntax_attributes = original_attributes } = desc ast in
       let attr =
@@ -567,7 +567,7 @@ module Make_with_attribute
             ; loc = !Ast_helper.default_loc
             }
         ; attr_loc = !Ast_helper.default_loc
-        ; attr_payload = Option.value payload ~default:(PStr [])
+        ; attr_payload = payload
         }
       in
       { desc; jane_syntax_attributes = attr :: original_attributes }
@@ -622,14 +622,14 @@ module Make_with_extension_node
 
     let embedding_syntax = Embedding_syntax.Extension_node
 
-    let make_jane_syntax name ?payload ast =
+    let make_jane_syntax name ?(payload = PStr []) ast =
       make_extension_use
         ast
         ~extension_node:
           (make_extension_node
              ({ txt = Embedded_name.to_string name
               ; loc = !Ast_helper.default_loc },
-              Option.value payload ~default:(PStr [])))
+              payload))
 
     let make_non_jane_syntax ast =
       desc ast
@@ -648,6 +648,19 @@ module Make_with_extension_node
         | Some name -> Some (name, ext_loc, ext_payload, body)
 end
 
+(********************************************************)
+(* Modules representing individual syntactic categories *)
+
+(* Note [Hiding internal details]
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   Each such module is first written with a '0' suffix. These '0'
+   modules are used internally as arguments to [Make_ast] to produce
+   non-'0' modules which are exported. This approach allows us to
+   hide details of these modules necessary for [Make_ast] but
+   unnecessary for external uses.
+*)
+
 (** The AST parameters for every subset of types; embedded with attributes. *)
 module Type_AST_syntactic_category = struct
   type ast = core_type
@@ -847,6 +860,7 @@ module type AST = sig
     of_ast_internal:(Feature.t -> ast -> 'a option) -> (ast -> 'a option)
 end
 
+(* See Note [Hiding internal details] *)
 module Make_ast (AST : AST_internal) : AST with type ast = AST.ast
                                             and type ast_desc = AST.ast_desc
                                             and type ast_info = AST.ast_info
@@ -897,6 +911,7 @@ module Make_ast (AST : AST_internal) : AST with type ast = AST.ast
     of_ast
 end
 
+(* See Note [Hiding internal details] *)
 module Expression = Make_ast(Expression0)
 module Pattern = Make_ast(Pattern0)
 module Module_type = Make_ast(Module_type0)

ocaml/parsing/jane_syntax_parsing.mli

@@ -152,7 +152,6 @@ end
     corresponding module of this module type.  We're adding these lazily as we
     need them. When you add another one, make sure also to add special handling
     in [Ast_iterator] and [Ast_mapper].
-
 *)
 module type AST = sig
   (** The AST type (e.g., [Parsetree.expression]) *)