[clang-tools-extra] [clang-tidy] Improve documentation of bugprone-pointer-arithmetic-on-polymorphic-object (PR #108324)

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tools-extra

@llvm/pr-subscribers-clang-tidy

Author: Mainak Sil (MainakSil)

<details>
<summary>Changes</summary>

This pull request addresses issue #<!-- -->107831 by improving the documentation for the `bugprone-pointer-arithmetic-on-polymorphic-object` Clang-Tidy check.

### Changes Made:
1. **Fixed Syntax Error**: Corrected the syntax for the virtual destructor in the `Base` class (`virtual ~Base();` instead of `virtual void ~Base();`).
2. **Improved Example**: Replaced the current example with a more accurate one, showing how pointer arithmetic on an array of derived objects can trigger a warning due to potential undefined behavior.
3. **Added Final Keyword Example**: Introduced an additional example where marking the derived class as `final` suppresses the warning, as further inheritance is disallowed.
4. **Clarified Documentation**: Added comments explaining how making a class `final` eliminates the risk of polymorphic pointer arithmetic and suppresses the warning.

This PR improves the clarity of the documentation and provides more relevant examples to help users better understand the behavior of this check.

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


1 Files Affected:

- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/pointer-arithmetic-on-polymorphic-object.rst (+28-10) 


``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/pointer-arithmetic-on-polymorphic-object.rst b/clang-tools-extra/docs/clang-tidy/checks/bugprone/pointer-arithmetic-on-polymorphic-object.rst
index 1884acd5f12b3e..4f926808f9e408 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/pointer-arithmetic-on-polymorphic-object.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/pointer-arithmetic-on-polymorphic-object.rst
@@ -19,20 +19,33 @@ Example:
 .. code-block:: c++
 
   struct Base {
-    virtual void ~Base();
+  virtual ~Base();
+  int i;
   };
 
   struct Derived : public Base {};
 
   void foo() {
-    Base *b = new Derived[10];
+  Base *b = new Derived[10];
 
-    b += 1;
-    // warning: pointer arithmetic on class that declares a virtual function can
-    // result in undefined behavior if the dynamic type differs from the
-    // pointer type
+  b += 1;
+  // warning: pointer arithmetic on class that declares a virtual function can
+  // result in undefined behavior if the dynamic type differs from the
+  // pointer type
 
-    delete[] static_cast<Derived*>(b);
+  delete[] static_cast<Derived*>(b);
+  }
+
+  // Another example showing array access with polymorphic objects.
+  int bar(const Derived d[]) {
+    return d[1].i; // warning due to pointer arithmetic on polymorphic object
+  }
+
+  // Making Derived final suppresses the warning
+  struct FinalDerived final : public Base {};
+
+  int baz(const FinalDerived d[]) {
+    return d[1].i; // no warning as FinalDerived is final
   }
 
 Options
@@ -50,14 +63,19 @@ Options
     void bar() {
       Base *b = new Base[10];
       b += 1; // warning, as Base declares a virtual destructor
-  
+
       delete[] b;
-  
+
       Derived *d = new Derived[10]; // Derived overrides the destructor, and
                                     // declares no other virtual functions
       d += 1; // warning only if IgnoreVirtualDeclarationsOnly is set to false
-  
+
       delete[] d;
+
+      FinalDerived *f = new FinalDerived[10];
+      f += 1; // no warning, FinalDerived is final and cannot be further derived
+
+      delete[] f;
     }
 
 References

``````````

</details>


https://github.com/llvm/llvm-project/pull/108324