3 files changed, 102 insertions, 11 deletions

diff --git a/libcxx/docs/DesignDocs/DebugMode.rst b/libcxx/docs/DesignDocs/DebugMode.rst
new file mode 100644
index 00000000000..166c733e663
--- /dev/null
+++ b/libcxx/docs/DesignDocs/DebugMode.rst
@@ -0,0 +1,100 @@
+==========
+Debug Mode
+==========
+
+.. contents::
+   :local
+
+.. _using-debug-mode:
+
+Using Debug Mode
+================
+
+Libc++ provides a debug mode that enables assertions meant to detect incorrect
+usage of the standard library. By default these assertions are disabled but
+they can be enabled using the ``_LIBCPP_DEBUG`` macro.
+
+**_LIBCPP_DEBUG** Macro
+-----------------------
+
+**_LIBCPP_DEBUG**:
+  This macro is used to enable assertions and iterator debugging checks within
+  libc++. By default it is undefined.
+
+  **Values**: ``0``, ``1``
+
+  Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
+  assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
+  which provides additional assertions about the validity of iterators used by
+  the program.
+
+  Note that this option has no effect on libc++'s ABI
+
+**_LIBCPP_DEBUG_USE_EXCEPTIONS**:
+  When this macro is defined ``_LIBCPP_ASSERT`` failures throw
+  ``__libcpp_debug_exception`` instead of aborting. Additionally this macro
+  disables exception specifications on functions containing ``_LIBCPP_ASSERT``
+  checks. This allows assertion failures to correctly throw through these
+  functions.
+
+Handling Assertion Failures
+---------------------------
+
+When a debug assertion fails the assertion handler is called via the
+``std::__libcpp_debug_function`` function pointer. It is possible to override
+this function pointer using a different handler function. Libc++ provides two
+different assertion handlers, the default handler
+``std::__libcpp_abort_debug_handler`` which aborts the program, and
+``std::__libcpp_throw_debug_handler`` which throws an instance of
+``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing
+assertion handler as follows:
+
+.. code-block:: cpp
+
+  #define _LIBCPP_DEBUG 1
+  #include <string>
+  int main() {
+    std::__libcpp_debug_function = std::__libcpp_throw_debug_function;
+    try {
+      std::string::iterator bad_it;
+      std::string str("hello world");
+      str.insert(bad_it, '!'); // causes debug assertion
+    } catch (std::__libcpp_debug_exception const&) {
+      return EXIT_SUCCESS;
+    }
+    return EXIT_FAILURE;
+  }
+
+Debug Mode Checks
+=================
+
+Libc++'s debug mode offers two levels of checking. The first enables various
+precondition checks throughout libc++. The second additionally enables
+"iterator debugging" which checks the validity of iterators used by the program.
+
+Basic Checks
+============
+
+These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
+
+The following checks are enabled by ``_LIBCPP_DEBUG``:
+
+  * FIXME: Update this list
+
+Iterator Debugging Checks
+=========================
+
+These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
+
+The following containers and STL classes support iterator debugging:
+
+  * ``std::string``
+  * ``std::vector<T>`` (``T != bool``)
+  * ``std::list``
+  * ``std::unordered_map``
+  * ``std::unordered_multimap``
+  * ``std::unordered_set``
+  * ``std::unordered_multiset``
+
+The remaining containers do not currently support iterator debugging.
+Patches welcome.
diff --git a/libcxx/docs/UsingLibcxx.rst b/libcxx/docs/UsingLibcxx.rst
index d6d1095b83c..de87c9c159d 100644
--- a/libcxx/docs/UsingLibcxx.rst
+++ b/libcxx/docs/UsingLibcxx.rst
@@ -133,17 +133,7 @@ or disable extended libc++ behavior, including enabling "debug mode" or
 thread safety annotations.
 
 **_LIBCPP_DEBUG**:
-  This macro is used to enable assertions and other debugging checks within
-  libc++. All debugging checks are disabled by default.
-
-  **Values**: ``0``, ``1``
-
-  Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
-  assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
-  which provides additional assertions about the validity of iterators used by
-  the program.
-
-  Note that this option has no effect on libc++'s ABI
+  See :ref:`using-debug-mode` for more information.
 
 **_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
   This macro is used to enable -Wthread-safety annotations on libc++'s
diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
index 0cac7fe98a9..c62dfe83392 100644
--- a/libcxx/docs/index.rst
+++ b/libcxx/docs/index.rst
@@ -127,6 +127,7 @@ Design Documents
 .. toctree::
    :maxdepth: 1
 
+   DesignDocs/DebugMode
    DesignDocs/CapturingConfigInfo
    DesignDocs/ABIVersioning
    DesignDocs/VisibilityMacros