[clang-tidy][NFC][doc] Improve documentation for modernize-use-equals… (#65231)

…-delete

So the purpose of the check is more clear. Update examples code to show
compliant code.

Fixes #65221

---------

Co-authored-by: Carlos Gálvez <[email protected]>

Author: carlosgalvezp

clang-tools-extra/clang-tidy/modernize/UseEqualsDeleteCheck.h

@@ -13,22 +13,9 @@
 
 namespace clang::tidy::modernize {
 
-/// Mark unimplemented private special member functions with '= delete'.
-/// \code
-///   struct A {
-///   private:
-///     A(const A&);
-///     A& operator=(const A&);
-///   };
-/// \endcode
-/// Is converted to:
-/// \code
-///   struct A {
-///   private:
-///     A(const A&) = delete;
-///     A& operator=(const A&) = delete;
-///   };
-/// \endcode
+/// Identifies unimplemented private special member functions, and recommends
+/// using ``= delete`` for them. Additionally, it recommends relocating any
+/// deleted member function from the ``private`` to the ``public`` section.
 ///
 /// For the user-facing documentation see:
 /// http://clang.llvm.org/extra/clang-tidy/checks/modernize/use-equals-delete.html

clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst

@@ -3,22 +3,37 @@
 modernize-use-equals-delete
 ===========================
 
-This check marks unimplemented private special member functions with ``= delete``.
-To avoid false-positives, this check only applies in a translation unit that has
-all other member functions implemented.
+Identifies unimplemented private special member functions, and recommends using
+``= delete`` for them. Additionally, it recommends relocating any deleted
+member function from the ``private`` to the ``public`` section.
+
+Before the introduction of C++11, the primary method to effectively "erase" a
+particular function involved declaring it as ``private`` without providing a
+definition. This approach would result in either a compiler error (when
+attempting to call a private function) or a linker error (due to an undefined
+reference).
+
+However, subsequent to the advent of C++11, a more conventional approach emerged
+for achieving this purpose. It involves flagging functions as ``= delete`` and
+keeping them in the ``public`` section of the class.
+
+To prevent false positives, this check is only active within a translation
+unit where all other member functions have been implemented. The check will
+generate partial fixes by introducing ``= delete``, but the user is responsible
+for manually relocating functions to the ``public`` section.
 
 .. code-block:: c++
 
-  struct A {
-  private:
+  // Example: bad
+  class A {
+   private:
     A(const A&);
     A& operator=(const A&);
   };
 
-  // becomes
-
-  struct A {
-  private:
+  // Example: good
+  class A {
+   public:
     A(const A&) = delete;
     A& operator=(const A&) = delete;
   };