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

[Carlos Galvez via cfe-commits]

Carlos =?utf-8?q?Gálvez?= <carlos.galvez at zenseact.com>,
Carlos =?utf-8?q?Gálvez?= <carlos.galvez at zenseact.com>


https://github.com/carlosgalvezp updated https://github.com/llvm/llvm-project/pull/65231:

>From 9c5fec5e31f31b59262646625b7d34f23d57d6cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20G=C3=A1lvez?= <carlos.galvez at zenseact.com>
Date: Sun, 3 Sep 2023 18:24:55 +0000
Subject: [PATCH 1/3] [clang-tidy][NFC][doc] Improve documentation for
 modernize-use-equals-delete

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

Fixes #65221
---
 .../checks/modernize/use-equals-delete.rst    | 26 ++++++++++++++-----
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst b/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
index c3de904e2538021..47de4185667a3ea 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
@@ -3,22 +3,34 @@
 modernize-use-equals-delete
 ===========================
 
+Prior to C++11, the only way to "delete" a given function was to make it
+``private`` and without definition, to generate a compiler error (calling
+private function) or a linker error (undefined reference).
+
+After C++11, the more idiomatic way to achieve this is by marking the functions
+as ``= delete``, and keeping them in the ``public`` section.
+
 This check marks unimplemented private special member functions with ``= delete``.
+Additionally, it warns about ``delete``'d functions still kept in the ``private``
+section, that should be moved to the ``public`` one instead.
+
 To avoid false-positives, this check only applies in a translation unit that has
-all other member functions implemented.
+all other member functions implemented. The check will generate partial fixes
+by adding ``= delete``, but the user must manually move it 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;
   };

>From aba8f0d712fd78db75a0387dde968e18d87b5fb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20G=C3=A1lvez?= <carlos.galvez at zenseact.com>
Date: Sun, 3 Sep 2023 18:39:48 +0000
Subject: [PATCH 2/3] Remove duplication

---
 .../clang-tidy/checks/modernize/use-equals-delete.rst    | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst b/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
index 47de4185667a3ea..a1fab68b0951b9d 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
@@ -10,14 +10,11 @@ private function) or a linker error (undefined reference).
 After C++11, the more idiomatic way to achieve this is by marking the functions
 as ``= delete``, and keeping them in the ``public`` section.
 
-This check marks unimplemented private special member functions with ``= delete``.
-Additionally, it warns about ``delete``'d functions still kept in the ``private``
-section, that should be moved to the ``public`` one instead.
-
+This check warns only on unimplemented private **special member functions**.
 To avoid false-positives, this check only applies in a translation unit that has
 all other member functions implemented. The check will generate partial fixes
-by adding ``= delete``, but the user must manually move it to the ``public``
-section.
+by adding ``= delete``, but the move the ``public`` section needs to be done
+manually.
 
 .. code-block:: c++
 

>From 63ad78a7e313761c627fb68245e56ccac41e86e2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20G=C3=A1lvez?= <carlos.galvez at zenseact.com>
Date: Sun, 3 Sep 2023 18:49:49 +0000
Subject: [PATCH 3/3] Apply suggestions

---
 .../checks/modernize/use-equals-delete.rst    | 34 +++++++++++--------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst b/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
index a1fab68b0951b9d..45039858fffdd3b 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/use-equals-delete.rst
@@ -3,20 +3,26 @@
 modernize-use-equals-delete
 ===========================
 
-Prior to C++11, the only way to "delete" a given function was to make it
-``private`` and without definition, to generate a compiler error (calling
-private function) or a linker error (undefined reference).
-
-After C++11, the more idiomatic way to achieve this is by marking the functions
-as ``= delete``, and keeping them in the ``public`` section.
-
-This check warns only on unimplemented private **special member functions**.
-To avoid false-positives, this check only applies in a translation unit that has
-all other member functions implemented. The check will generate partial fixes
-by adding ``= delete``, but the move the ``public`` section needs to be done
-manually.
-
-.. code-block:: c++
+Identifies unimplemented private special member functions, and recommends using
+``= delete`` for them, as well as relocating them from the ``private`` to the
+``public`` section.
+
+Before the introduction of C11, 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 C11, 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
 
   // Example: bad
   class A {