From 00116f6ff9c511e5ef43ecb0e08b5c692b9d7825 Mon Sep 17 00:00:00 2001
From: Rupayon Haldar <80724680+rupayon123@users.noreply.github.com>
Date: Mon, 5 Oct 2026 10:12:28 -0400
Subject: [PATCH 1/3] gh-158836: Clarify compound statement structure

---
 Doc/reference/compound_stmts.rst              | 23 +++++++++++--------
 .../2026-10-05-00-00-00.gh-issue-158836.rst   |  2 ++
 2 files changed, 15 insertions(+), 10 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index c13860eb3e9319a..a48a24b36caaa41 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -23,16 +23,19 @@ also syntactically compound statements.
    single: suite
    single: ; (semicolon)
 
-A compound statement consists of one or more 'clauses.'  A clause consists of a
-header and a 'suite.'  The clause headers of a particular compound statement are
-all at the same indentation level. Each clause header begins with a uniquely
-identifying keyword and ends with a colon.  A suite is a group of statements
-controlled by a clause.  A suite can be one or more semicolon-separated simple
-statements on the same line as the header, following the header's colon, or it
-can be one or more indented statements on subsequent lines.  Only the latter
-form of a suite can contain nested compound statements; the following is illegal,
-mostly because it wouldn't be clear to which :keyword:`if` clause a following
-:keyword:`else` clause would belong::
+A compound statement has a header and a 'suite.'  Many compound statements can
+also have additional clauses.  A clause consists of a header and a suite; the
+headers of clauses belonging to the same compound statement are at the same
+indentation level.  A header begins with a keyword and ends with a colon.  In
+:keyword:`async for`, :keyword:`async with`, and :keyword:`async def`, two
+keywords begin the header.  A :keyword:`match` statement instead has a suite
+containing indented :keyword:`case` blocks, each with its own header and suite.
+A suite is a group of statements controlled by its header.  It can be one or more
+semicolon-separated simple statements on the same line as the header, following
+the header's colon, or it can be one or more indented statements on subsequent
+lines.  Only the latter form of a suite can contain nested compound statements;
+the following is illegal, mostly because it wouldn't be clear to which
+:keyword:`if` clause a following :keyword:`else` clause would belong::
 
    if test1: if test2: print(x)
 
diff --git a/Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst b/Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst
new file mode 100644
index 000000000000000..c5191e4faa7f42e
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst
@@ -0,0 +1,2 @@
+Clarify how clauses relate to compound-statement headers and explain that
+``match`` statements contain indented ``case`` blocks.

From ece09b8f21b2511ad5f8635a8b65d587876e7ec5 Mon Sep 17 00:00:00 2001
From: Rupayon Haldar <80724680+rupayon123@users.noreply.github.com>
Date: Tue, 6 Oct 2026 09:36:11 -0400
Subject: [PATCH 2/3] gh-158836: Add documentation news entry

---
 .../2026-10-06-09-35-49.gh-issue-158836.d4db26.rst              | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst

diff --git a/Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst b/Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst
new file mode 100644
index 000000000000000..5f59202907a8955
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst
@@ -0,0 +1,2 @@
+Clarify the general structure of compound statements, including multi-keyword
+``async`` headers and the ``case`` blocks in ``match`` statements.

From 9529edcdfd90d99386c8174aee801a51eb9dc25a Mon Sep 17 00:00:00 2001
From: Rupayon Haldar <80724680+rupayon123@users.noreply.github.com>
Date: Tue, 6 Oct 2026 09:40:11 -0400
Subject: [PATCH 3/3] gh-158836: Remove unnecessary documentation news

---
 .../next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst  | 2 --
 .../2026-10-06-09-35-49.gh-issue-158836.d4db26.rst              | 2 --
 2 files changed, 4 deletions(-)
 delete mode 100644 Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst
 delete mode 100644 Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst

diff --git a/Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst b/Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst
deleted file mode 100644
index c5191e4faa7f42e..000000000000000
--- a/Misc/NEWS.d/next/Documentation/2026-10-05-00-00-00.gh-issue-158836.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Clarify how clauses relate to compound-statement headers and explain that
-``match`` statements contain indented ``case`` blocks.
diff --git a/Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst b/Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst
deleted file mode 100644
index 5f59202907a8955..000000000000000
--- a/Misc/NEWS.d/next/Documentation/2026-10-06-09-35-49.gh-issue-158836.d4db26.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Clarify the general structure of compound statements, including multi-keyword
-``async`` headers and the ``case`` blocks in ``match`` statements.