Merge pull request #9270 from gadmm/doc_stack_overflow

Documentation: Stack_overflow is reliable, Out_of_memory is not.
(cherry picked from commit 84f62eee5d26efb936cde0e799b7aaa39e46c010)

manual/manual/cmds/native.etex

@@ -200,13 +200,6 @@ allocation in the heap. That is, if a signal is delivered while in a
 piece of code that does not allocate, its handler will not be called
 until the next heap allocation.
 
-\item Stack overflow, typically caused by excessively deep recursion,
-is not always turned into a "Stack_overflow" exception like the
-bytecode compiler does.  The runtime system makes a best effort to
-trap stack overflows and raise the "Stack_overflow" exception, but
-sometimes it fails and a ``segmentation fault'' or another system fault
-occurs instead.
-
 \item On ARM and PowerPC processors (32 and 64 bits), fused
   multiply-add (FMA) instructions can be generated for a
   floating-point multiplication followed by a floating-point addition
@@ -238,4 +231,11 @@ not be linked and executed.  A workaround is to compile "M" with the
 not referenced.  See also the "Sys.opaque_identity" function from the
 "Sys" standard library module.
 
+\item Before 4.10, stack overflows, typically caused by excessively
+  deep recursion, are not always turned into a "Stack_overflow"
+  exception like with the bytecode compiler. The runtime system makes
+  a best effort to trap stack overflows and raise the "Stack_overflow"
+  exception, but sometimes it fails and a ``segmentation fault'' or
+  another system fault occurs instead.
+
 \end{itemize}

manual/manual/library/builtin.etex

@@ -215,8 +215,9 @@ exception Out_of_memory
 \end{ocamldoccode}
 \index{Outofmemory@\verb`Out_of_memory`}
 \begin{ocamldocdescription}
-   Exception raised by the garbage collector
-   when there is insufficient memory to complete the computation.
+   Exception raised by the garbage collector when there is
+   insufficient memory to complete the computation. (Not reliable for
+   allocations on the minor heap.)
 \end{ocamldocdescription}
 
 \begin{ocamldoccode}
@@ -225,10 +226,9 @@ exception Stack_overflow
 \index{Stackoverflow@\verb`Stack_overflow`}
 \begin{ocamldocdescription}
    Exception raised by the bytecode interpreter when the evaluation
-   stack reaches its maximal size. This often indicates infinite
-   or excessively deep recursion in the user's program.
-   (Not fully implemented by the native-code compiler;
-    see section~\ref{s:compat-native-bytecode}.)
+   stack reaches its maximal size. This often indicates infinite or
+   excessively deep recursion in the user's program. Before 4.10, it
+   was not fully implemented by the native-code compiler.
 \end{ocamldocdescription}
 
 \begin{ocamldoccode}

stdlib/stdlib.mli

@@ -79,13 +79,16 @@ exception Not_found
 
 exception Out_of_memory
 (** Exception raised by the garbage collector when there is
-   insufficient memory to complete the computation. *)
+   insufficient memory to complete the computation. (Not reliable for
+   allocations on the minor heap.) *)
 
 exception Stack_overflow
 (** Exception raised by the bytecode interpreter when the evaluation
    stack reaches its maximal size. This often indicates infinite or
-   excessively deep recursion in the user's program. (Not fully
-   implemented by the native-code compiler.) *)
+   excessively deep recursion in the user's program.
+
+   Before 4.10, it was not fully implemented by the native-code
+   compiler. *)
 
 exception Sys_error of string
   [@ocaml.warn_on_literal_pattern]