[clang-tools-extra] [clang-tidy] Fix alphabetical order check for multiline doc entries (PR #186950)

[Zeyi Xu via cfe-commits]

https://github.com/zeyi2 updated https://github.com/llvm/llvm-project/pull/186950

>From fd7fcb8a8cd7278dd86e249dd97821521d151952 Mon Sep 17 00:00:00 2001
From: mtx <mitchell.xu2 at gmail.com>
Date: Tue, 17 Mar 2026 12:26:35 +0800
Subject: [PATCH 1/2] [clang-tidy] Fix alphabetical order check for multiline
 doc entries

---
 .../tool/check_alphabetical_order.py          |  4 +-
 .../tool/check_alphabetical_order_test.py     | 43 +++++++++++++++++++
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
index 6a200e36b2715..992d644ce2ec3 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
@@ -202,7 +202,7 @@ def find_heading(lines: Sequence[str], title: str) -> Optional[int]:
 
 def extract_label(text: str) -> str:
     if m := DOC_LABEL_RN_RE.search(text):
-        return m.group("label")
+        return m.group("label").strip()
     return text
 
 
@@ -221,7 +221,7 @@ def _parse_bullet_blocks(lines: Sequence[str], start: int, end: int) -> BulletBl
     blocks: List[BulletItem] = []
     res = _scan_bullet_blocks(lines, first_bullet, n)
     for _, block in res.blocks_with_pos:
-        key: CheckLabel = extract_label(block[0])
+        key: CheckLabel = extract_label("".join(block))
         blocks.append((key, block))
 
     suffix: Lines = list(lines[res.next_index : n])
diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
index fa418e41ee8a8..1cb108016a707 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
@@ -358,6 +358,49 @@ def test_release_notes_handles_nested_sub_bullets(self) -> None:
         )
         self.assertEqual(out, expected_out)
 
+    def test_release_notes_handles_multiline_doc(self) -> None:
+        rn_text = textwrap.dedent(
+            """\
+            Changes in existing checks
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+            - Renamed :doc:`performance-faster-string-find
+              <clang-tidy/checks/performance/faster-string-find>` to
+              :doc:`performance-faster-string-operation
+              <clang-tidy/checks/performance/faster-string-operation>`.
+              The `performance-faster-string-find` name is kept as an alias.
+
+            - Renamed :doc:`hicpp-no-assembler <clang-tidy/checks/hicpp/no-assembler>`
+              to :doc:`portability-no-assembler
+              <clang-tidy/checks/portability/no-assembler>`. The `hicpp-no-assembler`
+              name is kept as an alias.
+
+            """
+        )
+
+        out = _mod.normalize_release_notes(rn_text.splitlines(True))
+
+        expected_out = textwrap.dedent(
+            """\
+            Changes in existing checks
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+            - Renamed :doc:`hicpp-no-assembler <clang-tidy/checks/hicpp/no-assembler>`
+              to :doc:`portability-no-assembler
+              <clang-tidy/checks/portability/no-assembler>`. The `hicpp-no-assembler`
+              name is kept as an alias.
+
+            - Renamed :doc:`performance-faster-string-find
+              <clang-tidy/checks/performance/faster-string-find>` to
+              :doc:`performance-faster-string-operation
+              <clang-tidy/checks/performance/faster-string-operation>`.
+              The `performance-faster-string-find` name is kept as an alias.
+
+
+            """
+        )
+        self.assertEqual(out, expected_out)
+
     def test_process_checks_list_normalizes_output(self) -> None:
         list_text = textwrap.dedent(
             """\

>From 75fa50161160efdb3938cf0f1fbcd9de54ec8aa4 Mon Sep 17 00:00:00 2001
From: mtx <mitchell.xu2 at gmail.com>
Date: Tue, 17 Mar 2026 13:53:37 +0800
Subject: [PATCH 2/2] fixup

---
 .../clang-tidy/tool/check_alphabetical_order.py  | 16 ++++++++++++----
 .../tool/check_alphabetical_order_test.py        |  5 +----
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
index 992d644ce2ec3..9493380bba8eb 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order.py
@@ -294,16 +294,24 @@ def _find_section_bounds(
         if (h_end := find_heading(lines, next_title)) is None:
             # Scan forward to the next heading-like underline.
             h_end = sec_start
-            while h_end + 1 < len(lines):
-                if lines[h_end].strip() and set(lines[h_end + 1].rstrip("\n")) == {"^"}:
+            while h_end < len(lines):
+                if (
+                    h_end + 1 < len(lines)
+                    and lines[h_end].strip()
+                    and set(lines[h_end + 1].rstrip("\n")) == {"^"}
+                ):
                     break
                 h_end += 1
         sec_end = h_end
     else:
         # Scan to end or until a heading underline is found.
         h_end = sec_start
-        while h_end + 1 < len(lines):
-            if lines[h_end].strip() and set(lines[h_end + 1].rstrip("\n")) == {"^"}:
+        while h_end < len(lines):
+            if (
+                h_end + 1 < len(lines)
+                and lines[h_end].strip()
+                and set(lines[h_end + 1].rstrip("\n")) == {"^"}
+            ):
                 break
             h_end += 1
         sec_end = h_end
diff --git a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
index 1cb108016a707..09e23ce55e00a 100644
--- a/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
+++ b/clang-tools-extra/clang-tidy/tool/check_alphabetical_order_test.py
@@ -109,6 +109,7 @@ def test_duplicate_detection_and_report(self) -> None:
               <clang-tidy/checks/bugprone/easily-swappable-parameters>` check by
               correcting a spelling mistake on its option
               ``NamePrefixSuffixSilenceDissimilarityTreshold``.
+
             """
         )
         self.assertEqual(report_str, expected_report)
@@ -161,7 +162,6 @@ def test_process_release_notes_with_unsorted_content(self) -> None:
 
                   Detect redundant parentheses.
 
-
                 """
             )
 
@@ -229,7 +229,6 @@ def test_process_release_notes_prioritizes_sorting_over_duplicates(self) -> None
                   exceptions from captures are now diagnosed, exceptions in the bodies of
                   lambdas that aren't actually invoked are not.
 
-
                 """
             )
             self.assertEqual(out, expected_out)
@@ -353,7 +352,6 @@ def test_release_notes_handles_nested_sub_bullets(self) -> None:
 
               - ``for`` loops are supported.
 
-
            """
         )
         self.assertEqual(out, expected_out)
@@ -396,7 +394,6 @@ def test_release_notes_handles_multiline_doc(self) -> None:
               <clang-tidy/checks/performance/faster-string-operation>`.
               The `performance-faster-string-find` name is kept as an alias.
 
-
             """
         )
         self.assertEqual(out, expected_out)