Document tests/gcov.

cov/src/graph.rs

@@ -177,6 +177,7 @@ impl Graph {
             if let Some(last_line) = self.report_block(block, &mut r) {
                 let function = &self[block.index];
                 let exit_block = function.exit_block(self.version);
+                // BTreeMap does not have IndexMut: See https://github.com/rust-lang/rust/issues/32170
                 let file = r.files.get_mut(&last_line.0).unwrap();
                 let branches = &mut file.lines.get_mut(&last_line.1).unwrap().branches;
                 for edge_ref in self.graph.edges(src) {

cov/tests/gcov.rs

@@ -1,3 +1,47 @@
+//! Test against output of GCOVR and LCOV.
+//!
+//! This test program will generate a report for `test-data/*/x.{gcno,gcda}`, and compare against `test-data/*/x.json`.
+//! It is considered failure if the report differs.
+//!
+//! The GCNO and GCDA files, along with GCOVR and LCOV output can be regenerated by running:
+//!
+//! ```sh
+//! cd test-data/
+//! ./rebuild.py clean
+//! ./rebuild.py
+//! ```
+//!
+//! Note that the GCNO and GCDA files will differ because gcc uses timestamp to differentiate between builds.
+//!
+//! The JSON files are created manually, and must be manually compared against GCOVR and LCOV to see if the output makes
+//! sense.
+//!
+//! ### Running `rebuild.py`
+//!
+//! `rebuild.py` primarily runs on the author's machine, so it is highly non-portable at the moment. To run the program,
+//! you will need the following executing in `$PATH`:
+//!
+//! | Executable | Component             |
+//! |-----------:|:----------------------|
+//! | `python3`  | Python 3.5+           |
+//! | `g++-7`    | GCC 7.1               |
+//! | `gcov-7`   | GCC 7.1               |
+//! | `clang++`  | clang 3.4+            |
+//! | `gcov`     | LLVM 3.4+ or GCC 4.6- |
+//! | `rustc`    | Rust nightly          |
+//! | `lcov`     | LCOV 1.13+            |
+//! | `genhtml`  | LCOV 1.13+            |
+//! | `gcovr`    | GCOVR 3.3+            |
+//!
+//! ### Creating a new test
+//!
+//! 1. Write the new source code in `test-data/src`. Must be a single file, of the form `filename.cpp` or `filename.rs`.
+//! 2. Create the folder `test-data/filename.clang/`, `test-data/filename.gcc7/` or `test-data/filename.rustc/`.
+//! 3. Run `rebuild.py` (no need to clean)
+//! 4. Fill in `test-data/filename.*/x.json`.
+//! 5. Run `cargo test` and update the JSON file or the code.
+
+
 extern crate cov;
 extern crate diff;
 extern crate serde_json;
@@ -55,6 +99,7 @@ fn run() -> io::Result<()> {
     Ok(())
 }
 
+/// Generates a report, and compare with the expected report. Returns both reports a JSON values.
 fn test(path: &Path) -> Result<(Value, Value)> {
     let mut interner = Interner::new();
     let mut graph = Graph::new();