[clang] [Clang] Document when to use ExtWarn and Extension (PR #223440)

[Nikolas Klauser via cfe-commits]

https://github.com/philnik777 updated https://github.com/llvm/llvm-project/pull/223440

>From 83761e7d3c0927451bff581eb2ed97e3f18a73d0 Mon Sep 17 00:00:00 2001
From: Nikolas Klauser <nikolasklauser at berlin.de>
Date: Mon, 14 Sep 2026 17:26:53 +0200
Subject: [PATCH 1/2] [Clang] Document when to use ExtWarn and Extension

---
 clang/docs/InternalsManual.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/clang/docs/InternalsManual.md b/clang/docs/InternalsManual.md
index 0d9ee745927aa..79b73dbf36a2a 100644
--- a/clang/docs/InternalsManual.md
+++ b/clang/docs/InternalsManual.md
@@ -114,6 +114,18 @@ severe that error recovery won't be able to recover sensibly from them (thus
 spewing a ton of bogus errors). One example of this class of error is failure
 to `#include` a file.
 
+##### Extension vs ExtWarn
+
+The `Extension` and `ExtWarn` are very closely related. Deciding when to use
+which one can be difficult. `ExtWarn` should be used in cases an extension is
+diagnosed and one of the following applies (or another good reason is stated):
+- the extension is likely to be used incorrectly (e.g. `-Wvla`)
+- the diagnosed code is likely wrong (e.g. `-Wmain`)
+- the extension is likely surprising in some cases (e.g. `SFINAEFailure`)
+- the extension is deprecated (e.g. `-Wauto-storage-class`)
+
+`Extension` should be used in all other circumstances.
+
 #### Diagnostic Wording
 
 The wording used for a diagnostic is critical because it is the only way for a

>From 2cbc4babfb98b66868e9d171be1a29bfb400fcc5 Mon Sep 17 00:00:00 2001
From: Nikolas Klauser <nikolasklauser at berlin.de>
Date: Mon, 21 Sep 2026 12:27:58 +0200
Subject: [PATCH 2/2] Update clang/docs/InternalsManual.md

Co-authored-by: Ambrose Leeb <aeternalmail at gmail.com>
---
 clang/docs/InternalsManual.md | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/clang/docs/InternalsManual.md b/clang/docs/InternalsManual.md
index 79b73dbf36a2a..c2925563aa388 100644
--- a/clang/docs/InternalsManual.md
+++ b/clang/docs/InternalsManual.md
@@ -116,13 +116,12 @@ to `#include` a file.
 
 ##### Extension vs ExtWarn
 
-The `Extension` and `ExtWarn` are very closely related. Deciding when to use
-which one can be difficult. `ExtWarn` should be used in cases an extension is
-diagnosed and one of the following applies (or another good reason is stated):
-- the extension is likely to be used incorrectly (e.g. `-Wvla`)
-- the diagnosed code is likely wrong (e.g. `-Wmain`)
-- the extension is likely surprising in some cases (e.g. `SFINAEFailure`)
-- the extension is deprecated (e.g. `-Wauto-storage-class`)
+Deciding whether to use `Extension` or `ExtWarn` can be difficult. 
+`ExtWarn` should be used if one of the following applies (or another good reason is stated):
+- the extension is likely to be used incorrectly (e.g. `-Wvla`);
+- the diagnosed code is likely wrong (e.g. `-Wmain`);
+- the extension is likely surprising in some cases (e.g. `SFINAEFailure`);
+- the extension is deprecated (e.g. `-Wauto-storage-class`).
 
 `Extension` should be used in all other circumstances.