Merge remote-tracking branch 'catalyst-oniongit/bug23739'

changes/bug23739

@@ -0,0 +1,3 @@
+  o Minor bugfixes (documentation):
+    - Document better how to read gcov and what our postprocessing scripts do.
+      Fixes bug 23739; bugfix on 0.2.9.1-alpha.

doc/HACKING/HelpfulTools.md

@@ -111,15 +111,19 @@ Running gcov for unit test coverage
 
 (On OSX, you'll need to start with `--enable-coverage CC=clang`.)
 
-Then, look at the .gcov files in `coverage-output`.  '-' before a line means
-that the compiler generated no code for that line.  '######' means that the
-line was never reached.  Lines with numbers were called that number of times.
-
 If that doesn't work:
 
    * Try configuring Tor with `--disable-gcc-hardening`
    * You might need to run `make clean` after you run `./configure`.
 
+Then, look at the .gcov files in `coverage-output`.  '-' before a line means
+that the compiler generated no code for that line.  '######' means that the
+line was never reached.  Lines with numbers were called that number of times.
+
+For more details about how to read gcov output, see the [Invoking
+gcov](https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html) chapter
+of the GCC manual.
+
 If you make changes to Tor and want to get another set of coverage results,
 you can run `make reset-gcov` to clear the intermediary gcov output.
 
@@ -128,9 +132,13 @@ a meaningful diff between them, you can run:
 
     ./scripts/test/cov-diff coverage-output1 coverage-output2 | less
 
-In this diff, any lines that were visited at least once will have coverage
+In this diff, any lines that were visited at least once will have coverage "1",
-"1".  This lets you inspect what you (probably) really want to know: which
+and line numbers are deleted.  This lets you inspect what you (probably) really
-untested lines were changed?  Are there any new untested lines?
+want to know: which untested lines were changed?  Are there any new untested
+lines?
+
+If you run ./scripts/test/cov-exclude, it marks excluded unreached
+lines with 'x', and excluded reached lines with '!!!'.
 
 Running integration tests
 -------------------------

doc/HACKING/WritingTests.md

@@ -91,6 +91,9 @@ coverage percentage.
 For a summary of the test coverage for each _function_, run
 `./scripts/test/cov-display -f ${TMPDIR}/*`.
 
+For more details on using gcov, including the helper scripts in
+scripts/test, see HelpfulTools.md.
+
 ### Comparing test coverage
 
 Sometimes it's useful to compare test coverage for a branch you're writing to
@@ -117,7 +120,8 @@ with LCOV_EXCL_START... LCOV_EXCL_STOP.  Note that older versions of
 lcov don't understand these lines.
 
 You can post-process .gcov files to make these lines 'unreached' by
-running ./scripts/test/cov-exclude on them.
+running ./scripts/test/cov-exclude on them.  It marks excluded
+unreached lines with 'x', and excluded reached lines with '!!!'.
 
 Note: you should never do this unless the line is meant to 100%
 unreachable by actual code.