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	Fri Jul 29 22:46:24 2016 +0300
@@ -275,12 +275,16 @@
    *filename* is used to construct the code object and may appear in tracebacks or
    :exc:`SyntaxError` exception messages.  This returns *NULL* if the code
    cannot be parsed or compiled.
+   
+   .. _basic-optimizations:
 
    The integer *optimize* specifies the optimization level of the compiler; a
    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). No other optimizations are currently
+   made. 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	Fri Jul 29 22:46:24 2016 +0300
@@ -236,9 +236,9 @@
 
 .. cmdoption:: -O
 
-   Turn on basic optimizations.  This changes the filename extension for
-   compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``.  See also
-   :envvar:`PYTHONOPTIMIZE`.
+   Turn on :ref:`basic optimizations <basic-optimizations>`. This changes the
+   filename extension for compiled (:term:`bytecode`) files from ``.pyc`` to
+   ``.pyo``. See also :envvar:`PYTHONOPTIMIZE`.
 
 
 .. cmdoption:: -OO