diff -r 10e0b57008fe Doc/c-api/veryhigh.rst
--- a/Doc/c-api/veryhigh.rst	Fri May 15 10:28:40 2015 +0300
+++ b/Doc/c-api/veryhigh.rst	Tue Jul 26 08:37:53 2016 +0300
@@ -280,7 +280,8 @@
    value of ``-1`` selects the optimization level of the interpreter as given by
    :option:`-O` options.  Explicit levels are ``0`` (no optimization;
    ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
-   or ``2`` (docstrings are removed too).
+   or ``2`` (docstrings are removed too). The exact behavior of these 
+   optimizations may change in future versions of CPython.
 
    .. versionadded:: 3.4
 
diff -r 10e0b57008fe Doc/using/cmdline.rst
--- a/Doc/using/cmdline.rst	Fri May 15 10:28:40 2015 +0300
+++ b/Doc/using/cmdline.rst	Tue Jul 26 08:37:53 2016 +0300
@@ -240,6 +240,11 @@
    compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``.  See also
    :envvar:`PYTHONOPTIMIZE`.
 
+   Currently, this means that assert statements are completely eliminated, as
+   are statement blocks of the form if ``__debug__: ...`` (so you can put your
+   debug code in such statements blocks and just run with -O to avoid that
+   debug code). This behavior may change in future versions of CPython.
+
 
 .. cmdoption:: -OO