From 60a5d65eade29adbbb16f22a333dab1ca2e99993 Mon Sep 17 00:00:00 2001
From: Marc Gibbons <1726961+marcgibbons@users.noreply.github.com>
Date: Mon, 20 May 2024 13:29:46 -0400
Subject: [PATCH] docs: explain partial coverage reports on generator
 expressions (#1789)

Ref #1617
---
 doc/branch.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/branch.rst b/doc/branch.rst
index f500287f8..a1a4e9d69 100644
--- a/doc/branch.rst
+++ b/doc/branch.rst
@@ -116,3 +116,16 @@ Here the while loop will never complete because the break will always be taken
 at some point.  Coverage.py can't work that out on its own, but the "no branch"
 pragma indicates that the branch is known to be partial, and the line is not
 flagged.
+
+Generator expressions
+=====================
+
+Generator expressions may also report partial branch coverage. Consider the
+following example::
+
+    value = next(i in range(1))
+
+While we might expect this line of code to be reported as covered, the
+generator did not iterate until ``StopIteration`` is raised, the indication
+that the loop is complete. This is another case
+where adding ``# pragma: no branch`` may be desirable.