[clang-tools-extra] [clang-tidy][docs] improve documentation on cppcoreguidelines-narrowing-conversions (#111510) (PR #118209)

[Jonas Toth via cfe-commits]

https://github.com/JonasToth updated https://github.com/llvm/llvm-project/pull/118209

>From f4345664e10ac6a9e87b33b1e816b685a1355bb6 Mon Sep 17 00:00:00 2001
From: Jonas Toth <development at jonas-toth.eu>
Date: Sun, 1 Dec 2024 12:02:13 +0100
Subject: [PATCH 1/2] [clang-tidy][docs] improve documentation on
 cppcoreguidelines-narrowing-conversions (#111510)

---
 .../narrowing-conversions.rst                 | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst
index 04260e75aa558f..6b0c3187b40874 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst
@@ -27,6 +27,39 @@ This check will flag:
  - All applications of binary operators with a narrowing conversions.
    For example: ``int i; i+= 0.1;``.
 
+Arithmetic with smaller integer types than ``int`` trigger implicit conversions,
+as explained under `"Integral Promotion" on cppreference.com
+<https://en.cppreference.com/w/cpp/language/implicit_conversion>`_.
+This check diagnoses more instances of narrowing than the compiler warning
+`-Wconversion` does. The example below demonstrates this behavior.
+
+.. code-block:: c++
+
+   // The following function definition demonstrates usage of arithmetic with
+   // integer types smaller than `int` and how the narrowing conversion happens
+   // implicitly.
+   void computation(short argument1, short argument2) {
+     // Arithmetic written by humans:
+     short result = argument1 + argument2;
+     // Arithmetic actually performed by C++:
+     short result = static_cast<short>(static_cast<int>(argument1) + static_cast<int>(argument2));
+   }
+
+   void recommended_resolution(short argument1, short argument2) {
+     short result = argument1 + argument2;
+     //           ^ warning: narrowing conversion from 'int' to signed type 'short' is implementation-defined
+
+     // The recommended way to resolve this issue with the GSL is one of two ways.
+     // Either by a cast that throws if a loss of precision would occur.
+     short result = gsl::narrow<short>(argument1 + argument2);
+     // Or it can be resolved without checking the result.
+     short result = gsl::narrow_cast<short>(argument1 + argument2);
+
+     // A classical `static_cast` will silence the warning as well if the GSL
+     // is not available.
+     short result = static_cast<short>(argument1 + argument2);
+   }
+
 
 Options
 -------

>From 6d8b442137a175c854190e780d2faf6b6976323e Mon Sep 17 00:00:00 2001
From: Jonas Toth <development at jonas-toth.eu>
Date: Sun, 15 Dec 2024 18:38:57 +0100
Subject: [PATCH 2/2] fixup! [clang-tidy][docs] improve documentation on
 cppcoreguidelines-narrowing-conversions (#111510)

---
 .../checks/cppcoreguidelines/narrowing-conversions.rst     | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst
index 6b0c3187b40874..7cc0b2809b4589 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst
@@ -49,10 +49,11 @@ This check diagnoses more instances of narrowing than the compiler warning
      short result = argument1 + argument2;
      //           ^ warning: narrowing conversion from 'int' to signed type 'short' is implementation-defined
 
-     // The recommended way to resolve this issue with the GSL is one of two ways.
-     // Either by a cast that throws if a loss of precision would occur.
+     // The cppcoreguidelines recommend to resolve this issue by using the GSL
+     // in one of two ways. Either by a cast that throws if a loss of precision
+     // would occur.
      short result = gsl::narrow<short>(argument1 + argument2);
-     // Or it can be resolved without checking the result.
+     // Or it can be resolved without checking the result risking invalid results.
      short result = gsl::narrow_cast<short>(argument1 + argument2);
 
      // A classical `static_cast` will silence the warning as well if the GSL