| Issue |
131931
|
| Summary |
The documentation of `SanitizerCoverage` is confusing
|
| Labels |
documentation,
clang,
coverage
|
| Assignees |
|
| Reporter |
cor3ntin
|
Myself, multiple other maintainers and users got confused about what `SanitizerCoverage` is and how it works.
[Its documentation](https://releases.llvm.org/20.1.0/tools/clang/docs/SanitizerCoverage.html) simply states
> LLVM has a simple code coverage instrumentation built in (SanitizerCoverage). It inserts calls to user-defined functions on function-, basic-block-, and edge- levels. Default implementations of those callbacks are provided and implement simple coverage reporting and visualization, however if you need just coverage visualization you may want to use [SourceBasedCodeCoverage](https://releases.llvm.org/20.1.0/tools/clang/docs/SourceBasedCodeCoverage.html) instead.
This does not make it clear that the intent is that this coverage tool is meant to be used alongside other sanitizers, which immediately brings a few questions
- Why is this related to other sanitizers at all?
- Can this be used independently of any other sanitizer?
- Which sanitizer can this be used with?
The names of the options (`-fsanitize-coverage-xxx`) and related tools (`anchovy) are also misleading and inconsistent.
There is better documentation in [SourceBasedCodeCoverage](https://releases.llvm.org/20.1.0/tools/clang/docs/SourceBasedCodeCoverage.html) which explains
> This document explains how to use Clang’s source-based code coverage feature. It’s called “source-based” because it operates on AST and preprocessor information directly. This allows it to generate very precise coverage data.
> Clang ships two other code coverage implementations:
> * [SanitizerCoverage](https://releases.llvm.org/20.1.0/tools/clang/docs/SanitizerCoverage.html) - A low-overhead tool meant for use alongside the various sanitizers. It can provide up to edge-level coverage.
> * gcov - A GCC-compatible coverage implementation which operates on DebugInfo. This is enabled by -ftest-coverage or --coverage.
But this is less visible.
It would be great to find ways to make all of that clearer. Possible options include
- Finding a better name (instrumented coverage?)
- Group the documentation of all 3 kinds of sanitizers under the same section (but still in different subpages)
- Add a better introductory description to the `SanitizerCoverage` page
![]()
_______________________________________________
llvm-bugs mailing list
llvm-bugs@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-bugs
