<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/131931>131931</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            The documentation of `SanitizerCoverage` is confusing
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            documentation,
            clang,
            coverage
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          cor3ntin
      </td>
    </tr>
</table>

<pre>
    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






</pre>
<img width="1" height="1" alt="" src="http://email.email.llvm.org/o/eJzMVk1v2zAS_TX0ZSBBpuKvgw-OUxcBWmCBFtszRY4kNhSp5VB21F-_ICXbSdruaRdYQEgskfP53jxSEOnGIu7Z6pGtnhZiCK3ze-l8aYO2i8qpcf91JDQ140foBhN0bxBcaNFDJ7QNQlv0BMIqGCj-alwA6Ww9ECoQlRsCXFoRgK2Lb8LqoH-hP7ozetEgWxegJ-PWXUAHuDj_Qjmw4hCf1eNzIFBODh3aIIJ2lq2eGN-2IfTEygPjJ8ZPHg0KQsqNOXe58w3jJ17ky7xg_BScM8T4SRph44JyMr7-lkvehs4wvgPSXW9GoCAC0jWT8hN8-fLPr9AKAjFtQZBOxT-TPWhLwd8ThWrQJoC2wPj298r5LofnuEzoA4EUxhAEl5qYKay1RQX1YGX0ReDs7SWLUFSCtMwq4-RLeo8tRNVgBgbPaCiHJ6zFEBOIqd6yInA1hNYRppCVkC8EwiP03p21ipBZdbe5VzoX6bF3PmjbpH1nTYMw-teEDD9GFPGMHnQNoxvAIir4OVC4O3hnkjZ1YoSLsGGuHtjq8ZsbvMRHQaiOTuGtaf8t7P_s_saAiCQKlU_Yf2915CASWBegEy8YiSoNCg8hMju0EfwQ26Xp-knTveaYRlzqcC6zQpjGwzjbkFbXiaIrTSg289Jq2YLuOlRaBDQjVF7bJhKwxgv8a0BKkLLiAJDBj3ac4msCj0YEVDHWR88gAghjWHma7Y7CTkbXrLRV2KNVaIMZI1-EHT-6uZv_SFneFkB-dHfRoZ23p24iWNHhTEQE10-8ZHzL1kVWXz1l1_Zlr6-vbF1EYCLn7qU5c7USVrbuPKYtHkEYctBpMijUlaraSmdJU4RpBnbKxiOkZENA_15q4uz-H7BxogG-9kboBPasRzMvp4Rv60lI50k6pkCfONsWbLcjoBQpq2KoD-JVowiDx6hJbwyiRKCC65fjWwfXj09QoRQxnA7gevRJNp2Fw7fvqfO9x947iUTOg7a1893UXqU9ymDGfCpFGOMuFL0EBw3a5AnO6MfoQmp6k64SQeRzH1KVQK3uCcLlSvgP2vxeBCNekzHjhwTxb_r8Pz9mMjiAcZcsfm9RTISeJaJ2PgF414c4KWfhtRvozSynIyQO3KzeMPSxeekgSOfArQP5m3ob6c4p_OfjMZOu60XQlflrt2YCvoX2Cauheba1m6HTBGhFFblSjZDVASnc5hechyx7l0hxeBxmkdQEBoniuRCTmJef401gMCqKSONRJE7U2iq4iDGdk0mHhTGTjIhZkNHn8A9HydVNWbSVZlAYBSiDk7aTJlxHPopRlJH78Z2GY6ZBeWJ8N1l-9i62t8UPKhEF0hgo4UVblWTtjdgOVqFPRhTjEKYjPMarhgAUtDFRZpSua_TpwB2qXjRIt7AHpe7Jahu8U4MMzo-gkKTXqcjYkRjkb5es6PImerdnofal2pU7scD9cvPAy3LzsC4W7b7YFHIj1lvkqtriRhZyXT1UildcLdeV2iz0nhd8VZTLLefl5qHI643gy3K52q5KtVuXG_ZQYCe0uc3KQhMNuF-Wy125XBhRoaF07eT8_f2Oc8aPjPN5kK5vt3sTjxdVv49-s2poiD0URlO4T-Ui6GBw__1PQP2HS-h0Z9W2WQze7N9PfqNDO1S5dB3jpxhn_pf13v1EGRg_pfLixM8Vnvf83wEAAP__5Rro6w">