manual: document exception A | pat

Changes

@@ -423,6 +423,9 @@ Working version
   (Florian Angeletti, review by Daniel Bünzli, Perry E. Metzger
   and Gabriel Scherer)
 
+- GPR#2187: document "exception A | pat" patterns
+  (Florian Angeletti, review by Perry E. Metzger and Jeremy Yallop)
+
 ### Compiler distribution build system:
 
 - GPR#1776: add -no-install-bytecode-programs and related configure options to

manual/manual/refman/patterns.etex

@@ -179,8 +179,9 @@ instance, the pattern "'0'"@'..'@"'9'" matches all characters that are digits.
 \subsubsection*{Exception patterns} \label{s:exception-match}
 (Introduced in OCaml 4.02)
 
-A new form of exception pattern, @ 'exception' pattern, @ is allowed
-only as a toplevel pattern under a "match"..."with" pattern-matching
+A new form of exception pattern, @ 'exception' pattern @, is allowed
+only as a toplevel pattern or inside a toplevel or-pattern under
+a "match"..."with" pattern-matching
 (other occurrences are rejected by the type-checker).
 
 Cases with such a toplevel pattern are called ``exception cases'',

manual/manual/tutorials/coreexamples.etex

@@ -550,10 +550,16 @@ let assoc_may_map f x l =
   | y -> f y;;
 \end{caml_example}
 Note that this construction is only useful if the exception is raised
-between "match"\ldots"with". Moreover, exceptions can only
-appear at the toplevel of such a pattern match.
-For instance, exception cases cannot currently be combined with an
-or-pattern: "exception A | exception B ->" \ldots .
+between "match"\ldots"with". Exception patterns can be combined
+with ordinary patterns at the toplevel,
+\begin{caml_example}{toplevel}
+let flat_assoc_opt x l =
+  match List.assoc x l with
+  | None | exception Not_found -> None
+  | Some _ as v -> v;;
+\end{caml_example}
+but they cannot be nested inside other patterns. For instance,
+the pattern "Some (exception A)" is invalid.
 
 When exceptions are used as a control structure, it can be useful to make
 them as local as possible by using a locally defined exception.