State the intent of Invalid_argument, Failure, and Sys_error

(Christophe Troestler)

This stems from the discussion https://github.com/ocaml/ocaml/pull/250
where the importance (or not) of pattern matching on the string
literal was raised.

git-svn-id: http://caml.inria.fr/svn/ocamldoc/trunk@16449 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02

1 files changed, 14 insertions, 5 deletions

diff --git a/manual/manual/library/builtin.etex b/manual/manual/library/builtin.etex
index b40cde3f7b..404f5608fb 100644
--- a/manual/manual/library/builtin.etex
+++ b/manual/manual/library/builtin.etex
@@ -181,7 +181,10 @@ exception Invalid_argument of string
 \index{Invalidargument@\verb`Invalid_argument`}
 \begin{ocamldocdescription}
    Exception raised by library functions to signal that the given
-   arguments do not make sense.
+   arguments do not make sense.  The string gives some information
+   to the programmer.  As a general rule, this exception should not
+   be caught, it denotes a programming error and the code should be
+   modified not to trigger it.
 \end{ocamldocdescription}
 
 \begin{ocamldoccode}
@@ -189,8 +192,11 @@ exception Failure of string
 \end{ocamldoccode}
 \index{Failure@\verb`Failure`}
 \begin{ocamldocdescription}
-   Exception raised by library functions to signal that they are
-   undefined on the given arguments.
+  Exception raised by library functions to signal that they are
+  undefined on the given arguments.  The string is meant to give some
+  information to the programmer; you must \emph{not} pattern match on
+  the string literal because it may change in future versions (use
+  \verb`Failure _` instead).
 \end{ocamldocdescription}
 
 \begin{ocamldoccode}
@@ -228,8 +234,11 @@ exception Sys_error of string
 \end{ocamldoccode}
 \index{Syserror@\verb`Sys_error`}
 \begin{ocamldocdescription}
-   Exception raised by the input/output functions to report
-   an operating system error.
+  Exception raised by the input/output functions to report an
+  operating system error.  The string is meant to give some
+  information to the programmer; you must \emph{not} pattern match on
+  the string literal because it may change in future versions (use
+  \verb`Sys_error _` instead).
 \end{ocamldocdescription}
 
 \begin{ocamldoccode}