[PATCH] D20715: [docs] Document the source-based code coverage feature

[Sean Silva via cfe-commits]

silvas added subscribers: MaggieYi, phillip.power.
silvas added a comment.

This is looking really good. So based on reading this, a rough sketch of how we can expand this to PGO would be something like:

- there is a separate PGO page that has similar structure, but is more tuned for the PGO use case.
- there is a separate page (maybe in the LLVM docs and not clang since other frontends might be using libprofile?) which describes "advanced usage of the profile runtime". That would cover the file and buffer API, `__llvm_profile_runtime`, runtime counter resetting and merging, etc.

Adding Maggie and Phillip, which are working on coverage at PlayStation.


================
Comment at: docs/SourceBasedCodeCoverage.rst:33
@@ +32,3 @@
+
+3. Create a report out of the generated profile.
+
----------------
Would it be possible to make these consistent with the later section headers?

================
Comment at: docs/SourceBasedCodeCoverage.rst:61
@@ +60,3 @@
+    # Step 1: Compile with coverage enabled.
+    % cc -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
+
----------------
Since these are clang's docs, we should just say `clang` (or `clang++`)

================
Comment at: docs/SourceBasedCodeCoverage.rst:91
@@ +90,3 @@
+Raw profiles have to be **indexed** before they can be used to generated
+coverage reports:
+
----------------
As a user, this would make me ask "why can't llvm-profdata do the indexing if I pass it a raw profile"?

I think the answer is largely that in a real program there are multiple profraws, so you need to merge them first. You probably want to mention that.

================
Comment at: docs/SourceBasedCodeCoverage.rst:140
@@ +139,3 @@
+    # Step 3(c): Create a coverage summary.
+    % llvm-cov report ./foo -instr-profile=foo.profdata
+
----------------
Can you show example output? That is one of the most useful things in a how-to document like this. (for example, a person reading this might be a prospective user of the feature, and seeing the output is valuable to them to see if it provides what they want)

================
Comment at: docs/SourceBasedCodeCoverage.rst:149
@@ +148,3 @@
+* Raw profiles can be discarded after they are indexed. It **is** possible for
+  instrumented programs to merge profiling information directly into an existing
+  raw profile on disk. The details are out of this document's scope.
----------------
Small wording nit: Instead of saying "It is possible for an instrumented program to..." I would say something like "Advanced use of the profile runtime library allows an instrumented program to..." or something like that.


http://reviews.llvm.org/D20715