Coverage: doc improvements.

R=mmoroz@chromium.org,liaoyuke@chromium.org

Change-Id: Iaf6f74ab4bc02d95f93f0ffc44ccf20e0d1f0682
Bug: 833912
Reviewed-on: https://chromium-review.googlesource.com/1056153
Commit-Queue: Abhishek Arya <inferno@chromium.org>
Reviewed-by: Max Moroz <mmoroz@chromium.org>
Cr-Commit-Position: refs/heads/master@{#558035}

docs/code_coverage.md

@@ -11,12 +11,12 @@ Table of contents:
 - [Contacts](#contacts)
 - [FAQ](#faq)
 
-Chromium uses Clang source-based code coverage, this [documentation] explains
+Chromium uses Clang source-based code coverage. This [documentation] explains
 how to use Clang’s source-based coverage features in general.
 
-In this doc, we first introduce a code coverage script that can be used to
-generate code coverage reports for Chromium code in one command, and then dive
-into details to describe the code coverage reports generation workflow.
+In this document, we first introduce a code coverage script that can be used to
+generate code coverage reports for Chromium code in one command, and then
+describe the code coverage reports generation workflow.
 
 ## Coverage Script
 The [coverage script] automates the process described below and provides a
@@ -37,22 +37,34 @@ $ python tools/code_coverage/coverage.py \
     -f url/ -f crypto/
 ```
 The command above builds `crypto_unittests` and `url_unittests` targets and then
-runs each with the command and arguments specified by the `-c` flag. For
-`url_unittests`, it only runs the test `URLParser.PathURL`. The coverage report
+runs them individually with their commands and arguments specified by the `-c` flag. 
+For `url_unittests`, it only runs the test `URLParser.PathURL`. The coverage report
 is filtered to include only files and sub-directories under `url/` and `crypto/`
 directories.
 
-Aside from automating the process, this script provides additional features to
+Aside from automating the process, this script provides visualization features to
 view code coverage breakdown by directories and by components, for example:
 
-Directory View:
+### Directory View
 
 ![code coverage report directory view]
 
-Component View:
+### Component View
 
 ![code coverage report component view]
 
+### Source View
+
+When you click on a particular source file in one of the views above, you can check
+per-line coverage information such as
+
+- Uncovered / Covered line fragments, lines and code blocks. This information can be 
+useful to identify areas of code that lack test coverage.
+- Per-line hit counts indicating how many times this line was hit by all tested targets. 
+This information can be useful to determine hot spots in your code.
+
+![code coverage source view]
+
 ## Workflow
 This section presents the workflow of generating code coverage reports using two
 unit test targets in Chromium repo as an example: `crypto_unittests` and
@@ -82,11 +94,11 @@ $ ninja -C out/coverage crypto_unittests url_unittests
 ```
 
 ### Step 2 Create Raw Profiles
-The next step is to run the instrumented binaries, and when the program exits it
-will write a raw profile for each process. Because Chromium runs tests in
-multiple processes, and the number of processes spawned can be as many as a few
-hundred, which results in the generation of a few hundred gigabytes’ raw
-profiles, to limit the number of raw profiles, `%Nm` pattern in
+The next step is to run the instrumented binaries. When the program exits, it 
+writes a raw profile for each process. Because Chromium runs tests in
+multiple processes, the number of processes spawned can be as many as a few
+hundred, resulting in the generation of a few hundred gigabytes’ raw
+profiles. To limit the number of raw profiles, `%Nm` pattern in
 `LLVM_PROFILE_FILE` environment variable is used to run tests in multi-process
 mode, where `N` is the number of raw profiles. With `N = 4`, the total size of
 the raw profiles are limited to a few gigabytes.
@@ -103,10 +115,10 @@ crypto_unittests.3657994905831792357_3.profraw
 ### Step 3 Create Indexed Profile
 Raw profiles must be indexed before generating code coverage reports, and this
 is done using the `merge` command of `llvm-profdata` tool, which merges multiple
-raw profiles (.profraw) and index them to create a single profile (.profdata).
+raw profiles (.profraw) and indexes them to create a single profile (.profdata).
 
 At this point, all the raw profiles can be thrown away because their information
-are already contained in the indexed profile.
+is already contained in the indexed profile.
 
 ```
 $ llvm-profdata merge -o out/report/coverage.profdata \
@@ -122,10 +134,12 @@ out/report/coverage.profdata
 
 ### Step 4 Create Coverage Reports
 Finally, `llvm-cov` is used to render code coverage reports. There are different
-report generation modes, and all of them require the indexed profile, all the
-built binaries and all the exercised source files to be available.
+report generation modes, and all of them require the following as input:
+- Indexed profile
+- All built target binaries
+- All exercised source files.
 
-For example, following command can be used to generate per-file line-by-line
+For example, the following command can be used to generate per-file line-by-line
 code coverage report:
 
 ```
@@ -156,7 +170,7 @@ see [crbug.com/831939].
 
 ### I am getting some warnings while using the script, is that fine?
 
-Usually that is not a critical issue, but in general we tend not to have any
+Usually this is not a critical issue, but in general we tend not to have any
 warnings. Please check the list of [known issues], and if there is a similar
 bug, leave a comment with the command you run, the output you get, and Chromium
 revision you use. Otherwise, please [file a new issue] providing the same
@@ -168,7 +182,8 @@ If a crash of any type occurs (Segmentation Fault, CHECK failure, ASan error),
 the crashing process will not dump coverage information necessary to generate
 code coverage report. For single-process applications (e.g. fuzz targets), that
 means no coverage will be reported at all. For multi-process applications, the
-report will be incomplete.
+report will be incomplete. It is important to fix the crash first. If this is
+happening only in the coverage instrumented build, please [file a bug].
 
 ### Is it possible to obtain code coverage from a full Chromium build?
 
@@ -189,6 +204,7 @@ For more information, please see [crbug.com/834781].
 [coverage script]: https://cs.chromium.org/chromium/src/tools/code_coverage/coverage.py
 [code coverage report directory view]: images/code_coverage_directory_view.png
 [code coverage report component view]: images/code_coverage_component_view.png
+[code coverage source view]: images/code_coverage_source_view.png
 [crbug.com/831939]: https://crbug.com/831939
 [crbug.com/834781]: https://crbug.com/834781
 [documentation]: https://clang.llvm.org/docs/SourceBasedCodeCoverage.html