Improve docs on using gcov

Add more explanation in doc/HACKING about how to read gcov output,
including a reference to the gcov documentation in the GCC manual.
Also add details about how our postprocessing scripts modify gcov
output.

diff --git a/changes/bug23739 b/changes/bug23739
new file mode 100644 (file)
index 0000000..3207b5e
--- /dev/null
+++ b/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.

diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md
index b8ba2aa408616f343798f4ef3bddd1c1556bb176..f919d08ec19c0333969c821839f5ba2d5889d404 100644 (file)
--- a/doc/HACKING/HelpfulTools.md
+++ b/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
-"1".  This lets you inspect what you (probably) really want to know: which
-untested lines were changed?  Are there any new untested lines?
+In this diff, any lines that were visited at least once will have coverage "1",
+and line numbers are deleted.  This lets you inspect what you (probably) really
+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
 -------------------------

diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md
index 4dae41e9222e508f0f444d7d21f2667c37c188ed..cc393494ec6f60bc26008c7ff3d936df43069dd4 100644 (file)
--- a/doc/HACKING/WritingTests.md
+++ b/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.