Index: docs/AddressSanitizer.rst
===================================================================
--- docs/AddressSanitizer.rst
+++ docs/AddressSanitizer.rst
@@ -60,7 +60,23 @@
     % clang -g -fsanitize=address example_UseAfterFree.o
 
 If a bug is detected, the program will print an error message to stderr and
-exit with a non-zero exit code. To make AddressSanitizer symbolize its output
+exit with a non-zero exit code. AddressSanitizer exits on the first detected
+error. This is by design. One reason: it makes the generated code smaller and
+faster (both by ~5%). Another reason: this makes fixing bugs unavoidable. With
+Valgrind, it is often the case that users treat Valgrind warnings as false
+positives (which they are not) and don't fix them.
+
+If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
+the asan library that is packaged with the compiler used to build the
+executable. (If the environment variable is not set, the process will try to
+re-exec.) Also keep in mind that when moving the executable to another machine,
+the asan library will also need to be copied over.
+
+Symbolizing the Reports
+=========================
+
+To make AddressSanitizer symbolize its output
 you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
 the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
 ``$PATH``):
@@ -100,14 +116,42 @@
 Note that on OS X you may need to run ``dsymutil`` on your binary to have the
 file\:line info in the AddressSanitizer reports.
 
-AddressSanitizer exits on the first detected error. This is by design.
-One reason: it makes the generated code smaller and faster (both by
-~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
-it is often the case that users treat Valgrind warnings as false
-positives (which they are not) and don't fix them.
+Issue Suppression
+=================
+
+AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!
+
+Suppressing Reports in External Libraries
+-----------------------------------------
+Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.
+
+.. code-block:: bash
+
+    ASAN_OPTIONS=suppressions=MyASan.supp
 
-``__has_feature(address_sanitizer)``
-------------------------------------
+Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.
+
+.. code-block:: bash
+
+    interceptor_via_fun:NameOfCFunctionToSuppress
+    interceptor_via_fun:-[ClassName objCMethodToSuppress:]
+    interceptor_via_lib:NameOfTheLibraryToSuppress
+
+Conditional Compilation with ``__has_feature(address_sanitizer)``
+-----------------------------------------------------------------
 
 In some cases one may need to execute different code depending on whether
 AddressSanitizer is enabled.
@@ -122,8 +166,8 @@
     #  endif
     #endif
 
-``__attribute__((no_sanitize_address))``
------------------------------------------------
+Disabling Instrumentation with ``__attribute__((no_sanitize_address))``
+-----------------------------------------------------------------------
 
 Some code should not be instrumented by AddressSanitizer. One may use the
 function attribute
@@ -133,17 +177,8 @@
 supported by other compilers, so we suggest to use it together with
 ``__has_feature(address_sanitizer)``.
 
-Initialization order checking
------------------------------
-
-AddressSanitizer can optionally detect dynamic initialization order problems,
-when initialization of globals defined in one translation unit uses
-globals defined in another translation unit. To enable this check at runtime,
-you should set environment variable
-``ASAN_OPTIONS=check_initialization_order=1``.
-
-Blacklist
----------
+Suppressing Errors in Recompiled Code (Blacklist)
+-------------------------------------------------
 
 AddressSanitizer supports ``src`` and ``fun`` entity types in
 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
@@ -172,11 +207,17 @@
     type:*BadInitClassSubstring*=init
     src:bad/init/files/*=init
 
-Memory leak detection
----------------------
+Limitations
+===========
 
-For the experimental memory leak detector in AddressSanitizer, see
-:doc:`LeakSanitizer`.
+* AddressSanitizer uses more real memory than a native run. Exact overhead
+  depends on the allocations sizes. The smaller the allocations you make the
+  bigger the overhead is.
+* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
+* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+  virtual address space. This means that tools like ``ulimit`` may not work as
+  usually expected.
+* Static linking is not supported.
 
 Supported Platforms
 ===================
@@ -184,24 +225,12 @@
 AddressSanitizer is supported on
 
 * Linux i386/x86\_64 (tested on Ubuntu 12.04);
-* MacOS 10.6 - 10.9 (i386/x86\_64).
+* OS X 10.6 - 10.11 (i386/x86\_64).
 * Android ARM
 * FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
 
 Ports to various other platforms are in progress.
 
-Limitations
-===========
-
-* AddressSanitizer uses more real memory than a native run. Exact overhead
-  depends on the allocations sizes. The smaller the allocations you make the
-  bigger the overhead is.
-* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
-* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
-  virtual address space. This means that tools like ``ulimit`` may not work as
-  usually expected.
-* Static linking is not supported.
-
 Current Status
 ==============
 
@@ -209,6 +238,25 @@
 3.1. The test suite is integrated into CMake build and can be run with ``make
 check-asan`` command.
 
+Additional Checks
+=================
+
+Initialization order checking
+-----------------------------
+
+AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+``ASAN_OPTIONS=check_initialization_order=1``.
+
+Memory leak detection
+---------------------
+
+For the experimental memory leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`.
+
+
 More Information
 ================