Doc tweaks.

4 files changed, 41 insertions, 40 deletions

diff --git a/coverage/control.py b/coverage/control.py
index 4bcb4ed4..24fed7b9 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -30,8 +30,7 @@ class coverage(object):
 
     def __init__(self, data_file=None, data_suffix=False, cover_pylib=False,
                 auto_data=False, timid=False, branch=False):
-        """Create a new coverage measurement context.
-        
+        """        
         `data_file` is the base name of the data file to use, defaulting to
         ".coverage".  `data_suffix` is appended to `data_file` to create the
         final file name.  If `data_suffix` is simply True, then a suffix is
@@ -49,7 +48,8 @@ class coverage(object):
         used.  This is important for some environments where manipulation of
         tracing functions breaks the faster trace function.
         
-        If `branch` is true, then measure branch execution.
+        If `branch` is true, then branch coverage will be measured in addition
+        to the usual statement coverage.
 
         """
         from coverage import __version__
diff --git a/doc/branch.rst b/doc/branch.rst
index 19be019a..1966b45d 100644
--- a/doc/branch.rst
+++ b/doc/branch.rst
@@ -18,20 +18,18 @@ For example::
         
     my_partial_fn(1)
     
-In this code, the if on line 2 could branch to either line 3 or line 4.
-Statement coverage would show all lines of the function as executed.  But the
-if is always true, so line 2 never jumps to line 4.  Even though line 4 is
-executed, coverage.py knows that it was never because of a branch from line
-2.
+In this code, line 2 is an ``if`` statement which can go next to either line 3
+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 would flag this code as not fully covered because of the
-missing jump from line 2 to line 4.
+Branch coverage will flag this code as not fully covered because of the missing
+jump from line 2 to line 4.
 
 
 How to measure branch coverage
 ------------------------------
 
-To measure branch coverage, run coverage.py with the --branch flag::
+To measure branch coverage, run coverage.py with the ``--branch`` flag::
 
     coverage run --branch myprog.py
     
@@ -41,10 +39,13 @@ covered total for each file.  The coverage percentage for a file is the
 actual executions divided by the execution opportunities.  Each line in the
 file is an execution opportunity, as is each branch destination.
 
-Currently, only HTML reports give 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.
+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.
+
+The XML report produced by "coverage xml" also includes branch information,
+including separate statement and branch coverage percentages.  Each line is
+annotated with 
 
 
 How it works
@@ -59,11 +60,15 @@ The idea of tracking how lines follow each other was from C. Titus Brown.
 Thanks, Titus!
 
 
+Excluding code
+--------------
+
+If you have excluded 
 Problems
 --------
 
 Some Python constructs are difficult to measure properly.  For example, an
-infinite loop will be marked as partially executed::
+unconditional loop will be marked as partially executed::
 
     while True:                         # line 1
         if some_condition():            #      2
@@ -73,17 +78,4 @@ infinite loop will be marked as partially executed::
     keep_working()                      #      6
 
 Because the loop never terminates naturally (jumping from line 1 to 6),
-coverage.py thinks the branch is partially executed. 
-
-Currently, if you exclude code from coverage testing, a branch into that code
-will still be considered executable, and may result in the branch being
-flagged.
-
-
-Other work
-----------
-
-One interesting side effect of tracking line transitions: we know where some
-exceptions happened because a transition happens that wasn't predicted by the
-static analysis.  Currently, I'm not doing anything with this information.
-Any ideas?
+coverage.py considers the branch partially executed. 
diff --git a/doc/excluding.rst b/doc/excluding.rst
index 0dfee514..1072e5b1 100644
--- a/doc/excluding.rst
+++ b/doc/excluding.rst
@@ -52,7 +52,7 @@ For example, you might decide that __repr__ functions are usually only used
 in debugging code, and are uninteresting to test themselves.  You could exclude
 all of them by adding a regex to the exclusion list::
 
-    coverage.exclude("def __repr__")
+    coverage.exclude('def __repr__')
     
 Here's a list of exclusions I've used::
 
diff --git a/doc/index.rst b/doc/index.rst
index 10a92a59..80295304 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,6 +8,7 @@ coverage.py
 :history: 20090707T205200, changes for 3.0.1

 :history: 20090913T084400, new command line syntax

 :history: 20091004T211900, version 3.1

+:history: 20091127T155100, version 3.2

 

 

 Coverage.py is a tool for measuring code coverage of Python programs. It

@@ -18,8 +19,8 @@ Coverage measurement is typically used to gauge the effectiveness of tests. It
 can show which parts of your product code are being exercised by tests, and

 which are not.

 

-The latest version is 3.1, released 4 October 2009.  It is supported on Python

-2.3 through 3.1.

+The latest version is 3.2, released ?? November 2009.

+It is supported on Python 2.3 through 3.1.

 

 

 Quick start

@@ -27,11 +28,12 @@ Quick start
 

 Getting started is easy:

 

-#.  Install coverage.py from the

-    `coverage page on the cheeseshop <http://pypi.python.org/pypi/coverage>`_,

+#.  Install coverage.py from the `coverage page on the Python Package Index`__,

     or by using "easy_install coverage".  You may need to install the

     python-dev support files, for example with "apt-get install python-dev".

 

+__ http://pypi.python.org/pypi/coverage

+

 #.  Use ``coverage run`` to execute your program and gather data:

 

     .. code-block:: console

@@ -59,7 +61,9 @@ Getting started is easy:
         $ coverage html -d htmlcov

 

     Then visit htmlcov/index.html in your browser, to see a

-    `report like this </code/coverage/sample_html/index.html>`_.

+    `report like this`__.

+

+__ /code/coverage/sample_html/index.html

 

 

 Using coverage.py

@@ -71,20 +75,24 @@ If you need more control over how your project is measured, you can use the
 :ref:`API <api>`.

 

 Some test runners provide coverage integration to make it easy to use coverage

-while running tests.  For example, `nose <http://somethingaboutorange.com/mrl/projects/nose>`_

-has a `cover plug-in <http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html>`_.

+while running tests.  For example, `nose`_ has a `cover plug-in`_.

 

 You can fine-tune coverage's view of your code by directing it to ignore parts

 that you know aren't interesting.  See :ref:`Excluding Code <excluding>` for

 details.

 

+.. _nose:           http://somethingaboutorange.com/mrl/projects/nose

+.. _cover plug-in:  http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html

+

 

 History

 -------

 

-Coverage.py was originally written by `Gareth Rees <http://garethrees.org/>`_.

-Ned Batchelder has maintained and extended it since 2004.

+Coverage.py was originally written by `Gareth Rees`_.

+Since 2004, `Ned Batchelder`_ has maintained and extended it.

 

+.. _Gareth Rees:    http://garethrees.org/

+.. _Ned Batchelder: http://nedbatchelder.com

 

 

 More information

@@ -96,6 +104,7 @@ More information
     cmd

     api

     excluding

+    branch

     faq

     changes