Improve partial branch documentation: add missing branch examples #2092

Ayisha-Mohammed · 2025-11-20T15:49:48Z

This PR improves the partial branch coverage documentation by adding the missing examples.
Fixes #1597

nedbat · 2025-11-20T16:21:44Z

Thanks for getting this started!

I think all the examples should be put in branch.rst, since they will be helpful for people looking at the HTML report also. You can put something in cmd_report.rst that explains what -> means, and reference the examples in branch.rst for more details.

For the formatting, try using make dochtml on your machine to see the finished HTML files. This can help you get the RST markup correct.

Ayisha-Mohammed · 2025-11-20T18:10:50Z

@nedbat made changes as requested.

nedbat

This is great. You've removed more text than I wanted you to, so we need to find the right balance.

nedbat · 2025-11-20T23:28:45Z

doc/branch.rst


 The HTML report gives information about which lines had missing branches. Lines
-that were missing some branches are shown in yellow, with an annotation at the
-far right showing branch destination line numbers that were not exercised.


I'm not sure why you removed "at the far right". I thought people might not notice it at the edge that usually has no information, so I wanted to direct their attention there.

nedbat · 2025-11-20T23:29:06Z

doc/branch.rst

 also include branch information, including separate statement and branch
 coverage percentages.

-


I like having extra space before headings. Can we keep the double-blank lines?

nedbat · 2025-11-20T23:29:47Z

doc/branch.rst

-flagged.
-
 Generator expressions
-=====================


This was meant to be a section within "Structurally partial branches", which is why it has a different header rule style.

nedbat · 2025-11-20T23:37:28Z

doc/branch.rst

-executions divided by the execution opportunities.  Each line in the file is an
-execution opportunity, as is each branch destination.
+covered total for each file. Each line in the file is an execution opportunity,
+as is each branch destination.


The last sentence mentions "execution opportunity", which was part of the sentence you dropped. I'm not sure the last sentence makes sense without it.

nedbat · 2025-11-20T23:38:49Z

doc/branch.rst

-will not be marked as a partial branch.
+Here the ``while`` loop will never exit normally, so it doesn't take both of
+its "possible" branches. For some of these constructs, such as ``while True:``
+and ``if 0:``, coverage.py understands what is going on.


Again, I feel like something important is lost by dropping the last sentence of the paragraph.

nedbat · 2025-11-20T23:51:56Z

doc/branch.rst

+    Missing:
+        12 -> 10
+
+Coverage.py will report::


We can probably skip this, since you've already said "12 -> 10" just above.

you mean to remove the case2 block?

I meant that we show "12->10" here on line 164 but we already showed it on line 160. But this whole example needs to be re-thought.

nedbat · 2025-11-20T23:52:59Z

doc/branch.rst

+
+If ``flag`` is always true, the false branch is never taken.
+
+The report will show::


we should include the word "missing" here somehow to underscore that the branches reported are the missing branches.

nedbat · 2025-11-20T23:53:28Z

doc/branch.rst

+A ``for`` loop has:
+
+* ``20->21`` (enter body)
+* ``21->20`` (repeat)


You used bullets here, but not above. We should choose a consistent style.

nedbat · 2025-11-21T00:50:59Z

doc/commands/cmd_report.rst

+Missing branches
+----------------
+
+Missing branches are shown such as ``12->10``.why is it backward?


This make it sound like branches are always reported in reverse. We should be clear that it's only sometimes.

nedbat · 2025-11-21T00:53:01Z

doc/commands/cmd_report.rst

+
+For detailed examples of how branch coverage works in loops and other control
+flow constructs (``if/else``, ``for`` loops, ``while`` loops, ``try/except``),
+see :doc:`branch </branch>`.


This reads as "see branch." which isn't the form we want. Use:

see :ref:`branch`.

Ayisha-Mohammed · 2025-11-21T04:23:36Z

@nedbat i've made the changes you requested. Thank you for the guidance , learnt a lot though this process.

nedbat · 2025-11-30T18:56:05Z

doc/branch.rst

+Case 2 — ``items = [1]``::
+
+    Missing:
+        12 -> 10


I'm sorry i didn't realize this earlier: this code doesn't have a branch from 12->10, because branches only occur where a statement can go next to two different places. Line 12 always goes to line 10, even on the last iteration of the loop. So we need to re-think this example.

@nedbat thank you , i fixed it

Improve partial branch documentation: add missing branch examples

458a93d

Ayisha-Mohammed added 3 commits November 20, 2025 22:53

Improve partial branch documentation: add missing branch examples

81375ed

Improve partial branch documentation: add missing branch examples

a2ecbff

moved examples to branch.rst

ca992c7

nedbat requested changes Nov 21, 2025

View reviewed changes

Ayisha-Mohammed added 2 commits November 21, 2025 09:22

branch coverage doc updations as per reviewer request

9a14143

fix:formmatting errors

c2f884d

Ayisha-Mohammed added 3 commits November 21, 2025 10:07

fix:formmatting errors

1fea818

fix:formmatting errors

fa04eed

Update branch coverage docs per reviewer request

0053ab6

nedbat reviewed Nov 30, 2025

View reviewed changes

Ayisha-Mohammed added 2 commits December 1, 2025 16:59

missing branch example fix

c33e66b

examples check

a5c20a7

		also include branch information, including separate statement and branch
		coverage percentages.


		If ``flag`` is always true, the false branch is never taken.

		The report will show::

Uh oh!

Improve partial branch documentation: add missing branch examples #2092

Are you sure you want to change the base?

Improve partial branch documentation: add missing branch examples #2092

Conversation

Ayisha-Mohammed commented Nov 20, 2025

Uh oh!

nedbat commented Nov 20, 2025

Uh oh!

Ayisha-Mohammed commented Nov 20, 2025

Uh oh!

nedbat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ayisha-Mohammed commented Nov 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants