Explain why we want the buildable-with-upstream restriction

ocaml/parsing/jane_syntax.ml

@@ -1168,8 +1168,9 @@ module N_ary_functions = struct
           | None -> body
           | Some { mode_annotations; type_constraint } ->
               let constrained_body =
-                (* We can't call [Location.ghostify] here, as we need
-                   [jane_syntax.ml] to build with the upstream compilerlibs. *)
+                (* We can't call [Location.ghostify] here, as we need this file
+                   to build with the upstream compiler; see Note [Buildable with
+                   upstream] in jane_syntax.mli for details. *)
                 let loc = { body.pexp_loc with loc_ghost = true } in
                 match type_constraint with
                 | Pconstraint ty -> Ast_helper.Exp.constraint_ body ty ~loc
@@ -1310,7 +1311,8 @@ module Layouts = struct
 
     (* Most things here are unprintable because we can't reference any
        [Printast] functions that aren't exposed by the upstream compiler, as we
-       want this file to be compatible with the upstream compiler-libs. *)
+       want this file to be compatible with the upstream compiler; ; see Note
+       [Buildable with upstream] in jane_syntax.mli for details. *)
     let report_error ~loc = function
       | Unexpected_wrapped_type _typ ->
         Location.errorf ~loc

ocaml/parsing/jane_syntax.mli

@@ -20,6 +20,24 @@
     For details on the rationale behind this approach (and for some of the gory
     details), see [Jane_syntax_parsing]. *)
 
+(******************************************************************************)
+
+(* Note [Buildable with upstream]
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   We want to make sure that the various [Jane_*] modules, along with
+   [Language_extension_kernel] and a small stub for [Language_extension], are
+   buildable with the upstream compiler and compiler-libs.  This allows us to
+   import these files into compatibility libraries such as
+   {{:https://github.com/janestreet/ppxlib_jane}ppxlib_jane}.  We have CI tests
+   which ensure that this property is maintained.
+
+   It is possible that at some point we'll really need to depend on new
+   functionality we provide elsewhere in the compiler; at that point, we can
+   look into providing stub implementations of these modules for use with the
+   upstream compiler instead.  For now, though, this is sufficient.
+*)
+
 (*********************************************)
 (* Individual features *)
 

ocaml/parsing/jane_syntax_parsing.ml

@@ -801,7 +801,8 @@ module Make_ast (AST : AST_internal) : AST with type ast = AST.ast = struct
   let make_entire_jane_syntax ~loc feature ast =
     AST.with_location
       (* We can't call [Location.ghostify] here, as we need
-         [jane_syntax_parsing.ml] to build with the upstream compilerlibs. *)
+         [jane_syntax_parsing.ml] to build with the upstream compiler; see
+         Note [Buildable with upstream] in jane_syntax.mli for details. *)
       (Ast_helper.with_default_loc { loc with loc_ghost = true } (fun () ->
         make_jane_syntax feature [] (ast ())))
       loc