[clang-tidy][docs][NFC] Improve documentation of bugprone-unhandled-exception-at-new

[Eugene.Zelenko]

clang-tools-extra/docs/clang-tidy/checks/bugprone-unhandled-exception-at-new.rst

65

Two excessive newlines.

[whisperity]

clang-tools-extra/docs/clang-tidy/checks/bugprone-unhandled-exception-at-new.rst

55

What does

exception types or exceptions

mean?

55

by the code is either superfluous or misleading. Did you mean that the exception should be caught and handled in the same scope where the allocation took place?

60

Is that the warning message the check prints?

60–61

69

[balazske]

Apply of review comments.

[balazske]

clang-tools-extra/docs/clang-tidy/checks/bugprone-unhandled-exception-at-new.rst

55

Now it is probably better. "Other exception" is any thrown exception of other class than the mentioned ones.

60

Warning text is changed to the exact checker's message.

[aaron.ballman]

LGTM aside from a small nit.

clang-tools-extra/docs/clang-tidy/checks/bugprone-unhandled-exception-at-new.rst

16–17

[balazske]

Applied the text changes.

clang-tools-extra/docs/clang-tidy/checks/bugprone-unhandled-exception-at-new.rst

 .. title:: clang-tidy - bugprone-unhandled-exception-at-new
 
 bugprone-unhandled-exception-at-new
 ===================================
 
 Finds calls to ``new`` with missing exception handler for ``std::bad_alloc``.
 
+Calls to ``new`` may throw exceptions of type ``std::bad_alloc`` that should
+be handled. Alternatively, the nonthrowing form of ``new`` can be
+used. The check verifies that the exception is handled in the function
+that calls ``new``.
+
+If a nonthrowing version is used or the exception is allowed to propagate out
+of the function no warning is generated.
+
+The exception handler is checked if it catches a ``std::bad_alloc`` or
+``std::exception`` exception type, or all exceptions (catch-all).
+The check assumes that any user-defined ``operator new`` is either
+``noexcept`` or may throw an exception of type ``std::bad_alloc`` (or one
+derived from it). Other exception class types are not taken into account.
+
 .. code-block:: c++
 
   int *f() noexcept {
-    int *p = new int[1000];
+    int *p = new int[1000]; // warning: missing exception handler for allocation failure at 'new'
+    // ...
+    return p;
+  }
+
+.. code-block:: c++
+
+  int *f1() { // not 'noexcept'
+    int *p = new int[1000]; // no warning: exception can be handled outside
+                            // of this function
+    // ...
+    return p;
+  }
+
+  int *f2() noexcept {
+    try {
+      int *p = new int[1000]; // no warning: exception is handled
+      // ...
+      return p;
+    } catch (std::bad_alloc &) {
+      // ...
+    }
+    // ...
+  }
+
+  int *f3() noexcept {
+    int *p = new (std::nothrow) int[1000]; // no warning: "nothrow" is used
     // ...
     return p;
   }
 
-Calls to ``new`` can throw exceptions of type ``std::bad_alloc`` that should
-be handled by the code. Alternatively, the nonthrowing form of ``new`` can be
-used. The check verifies that the exception is handled in the function
-that calls ``new``, unless a nonthrowing version is used or the exception
-is allowed to propagate out of the function (exception handler is checked for
-types ``std::bad_alloc``, ``std::exception``, and catch-all handler).
-The check assumes that any user-defined ``operator new`` is either
-``noexcept`` or may throw an exception of type ``std::bad_alloc`` (or derived
-from it). Other exception types or exceptions occurring in the object's
-constructor are not taken into account.