More overflowcheck documentation.

CHANGES.rst

@@ -8,6 +8,10 @@ Cython Changelog
 Features added
 --------------
 
+* Added a directive ``overflowcheck`` which raises an OverflowException when
+  arithmetic with C ints overflow.  This has a modest performance penalty, but
+  is much faster than using Python ints.
+
 * Calls to nested Python functions are resolved at compile time.
 
 * Type inference works across nested functions.

docs/src/reference/compilation.rst

@@ -151,8 +151,15 @@ Cython code.  Here is the list of currently supported directives:
 
 ``overflowcheck`` (True / False)
     If set to True, raise errors on overflowing C integer arithmetic
-    operations.  Incurs a slight runtime penalty, but much faster than
+    operations.  Incurs a modest runtime penalty, but is much faster than
     using Python ints.  Default is False.
+
+``overflowcheck.fold`` (True / False)
+    If set to True, and overflowcheck is True, check the overflow bit for
+    nested, side-effect-free arithmetic expressions once rather than at every
+    step.  Depending on the compiler, architecture, and optimization settings,
+    this may help or hurt performance.  A simple suite of benchmarks can be
+    found in ``Demos/overflow_perf.pyx``.  Default is True.
 
 ``embedsignature`` (True / False)
     If set to True, Cython will embed a textual copy of the call