From 20c1971db35ad44ccfb344525e9d1dc761522417 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron@aaronballman.com>
Date: Mon, 12 Oct 2015 12:57:55 +0000
Subject: [PATCH] Added documentation for
 misc-throw-by-value-catch-by-reference.

Patch by Tobias Langner.

llvm-svn: 250034
---
 clang-tools-extra/docs/clang-tidy/checks/list.rst     |  1 +
 .../checks/misc-throw-by-value-catch-by-reference.rst | 11 +++++++++++
 2 files changed, 12 insertions(+)
 create mode 100644 clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst

diff --git a/clang-tools-extra/docs/clang-tidy/checks/list.rst b/clang-tools-extra/docs/clang-tidy/checks/list.rst
index 974395eae693..71ebe3950045 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/list.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/list.rst
@@ -40,6 +40,7 @@ List of clang-tidy Checks
    misc-sizeof-container
    misc-static-assert
    misc-swapped-arguments
+   misc-throw-by-value-catch-by-reference
    misc-undelegated-constructor
    misc-uniqueptr-reset-release
    misc-unused-alias-decls
diff --git a/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst b/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst
new file mode 100644
index 000000000000..46eeb9c30f23
--- /dev/null
+++ b/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst
@@ -0,0 +1,11 @@
+misc-throw-by-value-catch-by-reference
+======================================
+
+Finds violations of the rule "Throw by value, catch by reference" presented for example in "C++ Coding Standards" by H. Sutter and A. Alexandrescu. This check also has the option to find violations of the rule "Throw anonymous temporaries" (https://www.securecoding.cert.org/confluence/display/cplusplus/ERR09-CPP.+Throw+anonymous+temporaries). The option is named "CheckThrowTemporaries" and it's on by default.
+
+Exceptions:
+- throwing string literals will not be flagged despite being a pointer. They are not susceptible to slicing and the usage of string literals is idomatic.
+- catching character pointers (char, wchar_t, unicode character types) will not be flagged to allow catching sting literals.
+- moved named values will not be flagged as not throwing an anonymous temporary. In this case we can be sure that the user knows that the object can't be accessed outside catch blocks handling the error.
+- throwing function parameters will not be flagged as not throwing an anonymous temporary. This allows helper functions for throwing.
+- re-throwing caught exception variables will not be flragged as not throwing an anonymous temporary. Although this can usually be done by just writing "throw;" it happens often enough in real code.