improve names and documentation

src/core/lwt.ml

@@ -712,14 +712,14 @@ open Basic_helpers
 
 (* Small helpers to avoid catching ocaml-runtime exceptions *)
 type exception_filter = exn -> bool
-let catch_all_filter = fun _ -> true
-let catch_not_runtime_filter = function
+let catch_filter__all = fun _ -> true
+let catch_filter__all_except_runtime = function
   | Out_of_memory -> false
   | Stack_overflow -> false
   | _ -> true
 let exception_filter =
   (* Default value: the legacy behaviour to avoid breaking programs *)
-  ref catch_all_filter
+  ref catch_filter__all
 let set_exception_filter f = exception_filter := f
 let filter_exception e = !exception_filter e
 

src/core/lwt.mli

@@ -2003,10 +2003,10 @@ val ignore_result : _ t -> unit
 
     Depending on the kind of programs that you write, you may need to treat
     exceptions thrown by the OCaml runtime (namely [Out_of_memory] and
-    [Stack_overflow] differently. This is because (a) these exceptions are not
-    reproducible (in that they are thrown at different points of your program
-    depending on the machine that your program runs on) and (b) recovering
-    from these errors may be impossible.
+    [Stack_overflow]) differently than all the other exceptions. This is because
+    (a) these exceptions are not reproducible (in that they are thrown at
+    different points of your program depending on the machine that your program
+    runs on) and (b) recovering from these errors may be impossible.
 
     The helpers below allow you to change the way that Lwt handles the two OCaml
     runtime exceptions [Out_of_memory] and [Stack_overflow]. *)
@@ -2016,12 +2016,12 @@ val ignore_result : _ t -> unit
     immediately. *)
 type exception_filter
 
-(** [catch_all_filter] is the default filter. With it the all the exceptions
+(** [catch_filter__all] is the default filter. With it the all the exceptions
     (including [Out_of_memory] and [Stack_overflow]) are caught and transformed
     into rejected promises. *)
-val catch_all_filter : exception_filter
+val catch_filter__all : exception_filter
 
-(** [catch_not_runtime_filter] is a filter which lets the OCaml runtime
+(** [catch_filter__all_except_runtime] is a filter which lets the OCaml runtime
     exceptions ([Out_of_memory] and [Stack_overflow]) go through all the Lwt
     abstractions and bubble all the way out of the call to [Lwt_main.run]. *)
 val catch_not_runtime_filter : exception_filter

src/unix/lwt_main.mli

@@ -39,13 +39,16 @@ let () = Lwt_main.run (main ())
       [Lwt_main.run] will raise [Failure]. This should be considered a logic
       error (i.e., code making such a call is inherently broken).
 
-      In addition, note that Lwt does not attempt to catch exceptions thrown by
-      the OCaml runtime. Specifically, Lwt lets [Out_of_memory] and
-      [Stack_overflow] exceptions traverse all of its functions and bubble up to
-      the caller of [Lwt_main.run]. Moreover because these exceptions are left
-      to traverse the call stack, they leave the internal data-structures in an
-      inconsistent state. For this reason, calling [Lwt_main.run] again after
-      such an exception will raise [Failure].
+      In addition, note that if you have set the exception filter to let runtime
+      exceptions bubble up (via
+      [Lwt.set_exception_filter catch_filter__all_except_runtime]) then Lwt does
+      not attempt to catch exceptions thrown by the OCaml runtime. Specifically,
+      in this case, Lwt lets [Out_of_memory] and [Stack_overflow] exceptions
+      traverse all of its functions and bubble up to the caller of
+      [Lwt_main.run]. Moreover because these exceptions are left to traverse the
+      call stack, they leave the internal data-structures in an inconsistent
+      state. For this reason, calling [Lwt_main.run] again after such an
+      exception will raise [Failure].
 
       It is not safe to call [Lwt_main.run] in a function registered with
       [Stdlib.at_exit], use {!Lwt_main.at_exit} instead. *)