Clean up comments after compiler dead-code removal

compiler/core/js_of_lam_block.ml

@@ -46,5 +46,3 @@ let set_field (field_info : Lam_compat.set_field_dbg_info) e i e0 =
   | Fld_record_extension_set name -> E.extension_assign e i name e0
   | Fld_record_inline_set name | Fld_record_set name ->
     E.record_assign e i name e0
-
-(* This dynamism commes from oo compilaton, it should not happen in record *)

compiler/core/js_of_lam_string.ml

@@ -30,5 +30,3 @@ module E = Js_exp_make
 *)
 
 let const_char (i : int) = E.int ~c:i (Int32.of_int @@ i)
-
-(* string [s[i]] expects to return a [ocaml_char] *)

compiler/core/js_packages_info.ml

@@ -133,9 +133,6 @@ let query_package_infos ({name; module_systems} : t)
       Package_found {rel_path; pkg_rel_path; suffix = k.suffix}
     | None -> Package_not_found)
 
-(* for a single pass compilation, [output_dir]
-   can be cached
-*)
 let add_npm_package_path (packages_info : t) (s : string) : t =
   if is_empty packages_info then
     Bsc_args.bad_arg "Set package name first using -bs-package-name"

compiler/core/lam_pass_count.ml

@@ -36,6 +36,11 @@ let absorb_info (x : used_info) (y : used_info) =
     x.times <- x0 + y0;
     if captured then x.captured <- true
 
+(* The global table [occ] records each let-bound identifier's number of uses and
+   whether it is captured by a function or loop. The local table [bv] tracks
+   locally let-bound variables and is reset when crossing functions and loops,
+   so uses of outer bindings are marked as captured. The optimizer uses the
+   captured flag to restrict inlining without inflating the occurrence count. *)
 let collect_occurs lam : occ_tbl =
   let occ : occ_tbl = Hash_ident.create 83 in
 
@@ -59,8 +64,8 @@ let collect_occurs lam : occ_tbl =
     | Some r -> r.times <- r.times + 1
     | None -> (
       (* ident is not locally bound, therefore this is a use under a lambda
-         or within a loop.  Increase use count by 2 -- enough so
-         that single-use optimizations will not apply. *)
+         or within a loop. Mark it as captured so that single-use
+         optimizations only apply when moving the value is safe. *)
       match Hash_ident.find_opt occ ident with
       | Some r -> absorb_info r {times = 1; captured = true}
       | None ->
@@ -78,8 +83,8 @@ let collect_occurs lam : occ_tbl =
     | Some r -> absorb_info r n
     | None -> (
       (* ident is not locally bound, therefore this is a use under a lambda
-         or within a loop.  Increase use count by 2 -- enough so
-         that single-use optimizations will not apply. *)
+         or within a loop. Mark it as captured so that single-use
+         optimizations only apply when moving the value is safe. *)
       match Hash_ident.find_opt occ ident with
       | Some r -> absorb_info r {n with captured = true}
       | None ->

compiler/ml/predef.mli

@@ -54,11 +54,15 @@ val path_tagged_template : Path.t
 
 val path_match_failure : Path.t
 val path_assert_failure : Path.t
+
 val build_initial_env :
   (Ident.t -> type_declaration -> 'a -> 'a) ->
   (Ident.t -> extension_constructor -> 'a -> 'a) ->
   'a ->
   'a
+(** Build the initial environment. Since [Predef] and [Env] are mutually
+    recursive, this function is parameterized over the empty environment and
+    the functions that add types and exceptions. *)
 
 (* To initialize linker tables *)
 

compiler/syntax/src/res_doc.mli

@@ -40,7 +40,15 @@ val question : t
 val tilde : t
 val equal : t
 val trailing_comma : t
+
 val will_break : t -> bool
+(** [will_break doc] checks whether [doc] contains forced line breaks. For each
+    [custom_layout], it only inspects the first alternative.
+
+    Forced breaks are not propagated through [custom_layout], because doing so
+    would always select the last layout the algorithm tries. Consumers can use
+    [will_break] to detect a forced break in a custom layout and explicitly add
+    [break_parent] to propagate it to the parent document. *)
 
 val to_string : width:int -> t -> string
 val debug : t -> unit [@@live]

compiler/syntax/src/res_scanner.mli

@@ -34,5 +34,5 @@ val scan_template_literal_token :
 
 val scan_regex : t -> Lexing.position * Lexing.position * Res_token.t
 
-(* Look ahead to see if the next non-whitespace character is a minus *)
+(* Look ahead to see if the next non-whitespace character is a slash *)
 val peek_slash : t -> bool