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

[JonasToth]

This PR improves the docs for this check to include an example of hidden narrowing conversions from the integer promotion rules in arithmetic.

[llvmbot]

@llvm/pr-subscribers-clang-tidy

@llvm/pr-subscribers-clang-tools-extra

Author: Jonas Toth (JonasToth)

Changes

This PR improves the docs for this check to include an example of hidden narrowing conversions from the integer promotion rules in arithmetic.

---

Full diff: https://github.com/llvm/llvm-project/pull/118209.diff

1 Files Affected:

• (modified) clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst (+15)

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..f4d1976ad4c688 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,21 @@ This check will flag:
  - All applications of binary operators with a narrowing conversions.
    For example: ``int i; i+= 0.1;``.
 
+Note that arithmetic with integer types may perform implicit conversions if the used integer types are smaller than ``int``.
+These rules are documented under `"Integral Promotion" on this cppreference.com <https://en.cppreference.com/w/cpp/language/implicit_conversion>`_
+page. The following example demonstrates this behavior and can be explored with `cppinsights.io <https://cppinsights.io/s/68553908>`_.
+
+.. 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));
+   }
+
 
 Options
 -------

[JonasToth]

@PiotrZSL I did assign you as reviewer because I noticed you do many reviews. Please remove yourself if that was not appropriate.
I did not contribute to clang-tidy for a longer period and not sure who to assign (if any!) for the PR. It was not meant offensively or so :)

[PiotrZSL]

• Formatting
• Please think about simplifying this.