Update the docs for 3.5 changes.

Author: nedbat

TODO.txt

@@ -5,15 +5,6 @@ Coverage TODO
     + warn if no data was collected
     - tie --source into reporting
 
-* 3.5b1
-
-- Update changes.rst
-- Document partial branch exclusion
-- Document HTML reporting
-    - Keyboard shortcuts
-    - Delta reporting
-
-
 * Soon
 
 + Better omit handling that ignores files during measurement.

doc/branch.rst

@@ -6,6 +6,7 @@ Branch coverage measurement
 
 :history: 20091127T201300, new for version 3.2
 :history: 20100725T211700, updated for 3.4.
+:history: 20110604T181700, updated for 3.5.
 
 .. highlight:: python
    :linenothreshold: 5
@@ -30,7 +31,7 @@ or line 4. Statement coverage would show all lines of the function as executed.
 But the if was never evaluated as false, so line 2 never jumps to line 4.
 
 Branch coverage will flag this code as not fully covered because of the missing
-jump from line 2 to line 4.
+jump from line 2 to line 4.  This is known as a partial branch.
 
 
 How to measure branch coverage
@@ -86,18 +87,34 @@ Because the ``else`` clause is excluded, the ``if`` only has one possible
 next line, so it isn't considered a branch at all.
 
 
-Problems
---------
+Structurally partial branches
+-----------------------------
 
-Some Python constructs are difficult to measure properly.  For example, an
-unconditional loop will be marked as partially executed::
+Sometimes branching constructs are used in unusual ways that don't actually
+branch.  For example::
 
-    while True:                         # line 1
-        if some_condition():            #      2
+    while True:
+        if cond:
             break
-        body_of_loop()                  #      4
+        do_something()
 
-    keep_working()                      #      6
+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.  In these cases, the line
+will not be marked as a partial branch.
+
+But there are many ways in your own code to write intentionally partial 
+branches, and you don't want coverage.py pestering you about them.  You can
+tell coverage.py that you don't want them flagged by marking them with a 
+pragma::
+
+    i = 0
+    while i < 999999999:    # pragma: no partial
+        if eventually():
+            break
+
+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 partial" pragma indicates that the branch is known to be partial, and
+the line is not flagged.
 
-Because the loop never terminates naturally (jumping from line 1 to 6),
-coverage.py considers the branch partially executed.

doc/cmd.rst

@@ -92,6 +92,18 @@ If you are measuring coverage in a multi-process program, or across a number of
 machines, you'll want the ``--parallel-mode`` switch to keep the data separate
 during measurement.  See :ref:`cmd_combining` below.
 
+During execution, coverage.py may warn you about conditions it detects that
+could affect the measurement process.  The possible warnings include:
+
+* "Trace function changed, measurement is likely wrong"
+
+* "Module has no Python source"
+
+* "Module was never imported"
+
+* "No data was collected"
+
+
 
 .. _cmd_datafile:
 
@@ -213,12 +225,20 @@ Lines are highlighted green for executed, red for missing, and gray for
 excluded.  The counts at the top of the file are buttons to turn on and off
 the highlighting.
 
+A number of keyboard shortcuts are available for navigating the report.
+Click the keyboard icon in the upper right to see the complete list.
+
 The ``-d`` argument specifies an output directory, defaulting to "htmlcov"::
 
     $ coverage html -d coverage_html
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
+Generating the HTML report can be time-consuming.  Stored with the HTML report
+is a data file that is used to speed up reporting the next time.  If you
+generate a new report into the same directory, coverage.py will skip
+generating unchanged pages, making the process faster.
+
 
 .. _cmd_annotation:
 

doc/config.rst

@@ -7,6 +7,7 @@ Configuration files
 :history: 20100223T201600, new for 3.3
 :history: 20100725T211700, updated for 3.4.
 :history: 20100824T092900, added ``precision``.
+:history: 20110604T184400, updated for 3.5.
 
 
 Coverage.py options can be specified in a configuration file.  This makes it
@@ -122,6 +123,12 @@ in reporting.  See :ref:`source` for details.
 ``omit`` (multi-string): a list of filename patterns, the files to leave out
 of reporting.  See :ref:`source` for details.
 
+``partial_branches`` (multi-string): a list of regular expressions.  Any line
+of code that matches one of these regexes is excused from being reported as
+a partial branch.  More details are in :ref:`branch`.  If you use this option,
+you are replacing all the partial branch regexes so you'll need to also
+supply the "pragma: no branch" regex if you still want to use it.
+
 ``precision`` (integer): the number of digits after the decimal point to
 display for reported coverage percentages.  The default is 0, displaying
 for example "87%".  A value of 2 will display percentages like "87.32%".

doc/excluding.rst

@@ -7,6 +7,7 @@ Excluding code from coverage
 :history: 20090613T090500, brand new docs.
 :history: 20100224T200900, updated for 3.3.
 :history: 20100725T211700, updated for 3.4.
+:history: 20110604T184400, updated for 3.5.
 
 
 You may have code in your project that you know won't be executed, and you want
@@ -76,7 +77,7 @@ all of them by adding a regex to the exclusion list::
     [report]
     exclude_lines = def __repr__
 
-Here's a list of exclusions I've used::
+For example, here's a list of exclusions I've used::
 
     [report]
     exclude_lines =
@@ -93,6 +94,9 @@ Note that when using the ``exclude_lines`` option in a configuration file, you
 are taking control of the entire list of regexes, so you need to re-specify the
 default "pragma: no cover" match if you still want it to apply.
 
+A similar pragma, "no partial", can be used to tailor branch coverage
+measurement.  See :ref:`branch` for details.
+
 
 Excluding source files
 ----------------------

doc/index.rst

@@ -17,6 +17,7 @@ coverage.py
 :history: 20100906T134700, updated for 3.4b2.
 :history: 20100919T163500, updated for 3.4 release.
 :history: 20110213T081200, claim true 3.2 compatibility.
+:history: 20110604T114800, update for 3.5b1
 
 Coverage.py is a tool for measuring code coverage of Python programs. It
 monitors your program, noting which parts of the code have been executed, then
@@ -26,8 +27,8 @@ Coverage measurement is typically used to gauge the effectiveness of tests. It
 can show which parts of your code are being exercised by tests, and which are
 not.
 
-The latest version is 3.4, released 19 September 2010.
-It is supported on Python 2.3 through 3.2.
+The latest version is 3.5b1, released ?? June 2011
+It is supported on Python versions 2.3 through 3.2.
 
 
 Quick start
@@ -39,7 +40,7 @@ Getting started is easy:
     or by using "easy_install coverage".  For a few more details, see
     :ref:`install`.
 
-#.  Use ``coverage run`` to execute your program and gather data:
+#.  Use ``coverage run`` to run your program and gather data:
 
     .. code-block:: console