<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=http://email.email.llvm.org/c/eJytVctu4zgQ_Br50oih0PYkOviQBwabw1529gcokpK4oUmBpOLx3281JdsxkDksZg3ClMh-VHdXt9qgT_sh5zFVm6dKfMdSTvp-7dzHYR1ijwMdVML2lHO07ZTNX6Yz0Xhl1kM-uEpsnH037nQnvb6b_PxCkDWJciBoTwfjM1mfsdngpSNtP0zsDc4oDyYZkmfjiboYDnxK0ahwgKo2mlozyA8b4qJBL5V4xqKU4VVGvaY3D1fW95RCJV5oCEcDH_zI8mcUkgHAstSJJPANYeoHsrkSD4kSlNgCNipZmN0C03Ew_iyV44mFEBrLF2H2cEZCaep7k3KC_Fkf6GZdHzJNSIKjU5ios16TJBV8jlJbVbAtASYEj1sVNJ69HUeTcS4zK8JUNNSFqJAZ4OgDtVK9EwAwOj6akLVYIAE7tGyCFMMOfl3Vr1X9NP__eaIxcj0jTEWTgpsKimOYHGedbdnD6Ewp4QzsIBGBKvm7lIja0y_q8se1EG-L2RHQmAagyZUdmY42D2R-SnaX6BAQI5PpM9zqW72s8mo7qsQjJ8oy6ko0VD08z3eEX7V7xpoZWe1eeW0-XXNmCrbzYfXw-qWfxZtPGcSh0P2vkP4rjB8WrVeSfWkaLq-z2cSS0yQLQSsh3rqZXMHRKFPihhxiYXweWCUoOYN8mQ_MT6Pm-o8StShWC1AhLhRerBf5FhbeWfs4WAV5r9yk4QWIL0EBPAQ-mXopXaAtuJN5UDA9bxWu0jdcRTRHdLJRVhdeJrDwfWYNZ0NNIDEz6UzXuddRDdv7wPxm8ye0MoiFrFEbpQfqEX2RMeCaZVZ49oLWZqYCmjMyZVIDxoH5YpQAR4eDhMa6jAL0xGidief2Z8OlN9n4Qb4bZruC4bhEL8TfX_TOdZJw2IGVJPLWlemLdpGnBTHPz7iAW64VexU36fthIOZSoNtx3yN_U7sGZrzw1F-2uzGGf1AivNqUJrb3fSeapl7p_UY3m0au5IT5Gfcak1mnHLxZTdHtf8-8WA17adqu3jVypxu1fcT2uLuXZiuatumaWpiVk61xac-9JIQ3Ryom8Ix2Wv0-ArsXtRD1fb29f9w1m_t1p5R-2NW6E60Q37b31bbGFLTu8pVcxX0x2U59wqWzqNr1Eq0HChpTAANhttmZ_Uvw3ZS4l24ZxR-5WwqH7quxwYyaj88f3fliVaLZl1D-BehMniM>52992</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            Confusing documentation or implementation of [[likely]] and [[unlikely]]
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            new issue
      </td>
    </tr>

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

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

<pre>
    https://clang.llvm.org/docs/AttributeReference.html#likely-and-unlikely tries to document intentional diverge in these attributes from the recommended behavior in the C++ standard. In doing so, however, the documentation reads as though it's showing how clang behaves when it's trying to show how the standard suggests it behaves. It's not until you find a contradiction in the second code snippet that you're forced to go back and try to understand what is going on.

My preferred resolution would be to implement the semantics as recommend by the C++ standard. However, I would personally document it with examples more like

```
if (condition) {
    [[likely]];
    whatever;
}
```

instead of

```
if (condition) {
    [[likely]] whatever;
}
```

Since the attribute is literally saying "If control passes through this location, this execution path is likely". It's saying this block, which includes `whatever`, is likely, not directly that `whatever` is likely.

If we decide to stick with the current implementation (ignored everywhere but branch points), then we should at least change the documentation to focus on how the compiler behaves, and then make it clear that "The C++ standard suggests we do it a different way, these are the differences".

See also https://github.com/llvm/llvm-project/issues/52990
</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJytVcGS6jYQ_BpzmVoKxLLAgcMuW6-yh1zy8gOyJNsKQnJJ8vL4-_TIBpaqzSGVUC5sSzM9rZmecR30Zd_l3Kdq9VqJH7iUk76dO_d5mofYYkEHlXB7zTnaesjmD9OYaLwy8y6fXCVWzh6NuzxJr58GP74QbE2iHAjew8n4TNZn3Gzw0pG2nya2BmuUO5MMySt4oiaGE69SNCqc4KqNptp08tOGOHnQoRJvuChlRJVRz-nDI5T1LaVQiQN14WwQgx_Z_spCMgEgS51Igl8XhrYjmyuxSZTgxAi4UcnCGBaczp3xV6scL2yEo7F9MeYIVyaUhrY1KSfYX_3BbvT1IdOAJDi6hIEa6zVJUsHnKLVVhdt0wITDY1cFjWdv-95krMvMjoCKhpoQFTIDHm2gWqojgQCz46UBWYuFErjDyyZYMe3g59XivVq8jv-_X6iPXM8IqGhScENhcQ6D46wzlj31zpQSjsROEidQJX-3ElF9-Ye6_HYvxMcE24MaywAyuasj09nmjswvyeESnQLOyGL6Srd6WUxXebUNVWLLibLMuhI7qjZv4x7hV63fcI2KrNbvfK2-bHNmCrfrYrV5_zbOFM2nDOFQaP5XSv-Wxk-L1ivJvjUNl9fZbGLJaZJFoJUQH80oruColylxQ3axKD537BKUHEkexgXzy6ix_r1ELQpqISrETcITerGvgXBk73NnFey9coNGFDC-HQrkYfAF6lC6QFtoJ_OgYHk-OtytH7SK05zRyUZZXXSZoMLjqBrOhhogYlbSVa5jr6MatvWB9c3wF7QyhIWsUR2lB-sefZEx4HbTrPAcBa3NSgU1Z2TKpDqMA_PNKAGPBgsJjXUbBeiJ3joTr-3PwKU3Gfwkj4bVrgAcp9ML8ec3vXOfJHzswE4SeWvK9EW7yMvEmOdnnMhN24qjiof0_TQwcynQ47hvkb-hnoMzXnjqT7enPoa_UCK82pQGxvuxFrvdYqb3K71b7eQs2-zM_hB8MyTWxGNmeFg_liI038mfMzMuXz8e48ZsiG7_37iKWbcX21WzWG02citF86Ll1khVbxqpN88LI5Zy5mRtXNozBSG8OVOBwDNzsHuxEGKxXDwvt-vdajlvlNKb9UI3ohbi5XlZAeUkrbt9MGdxXyjVQ5uw6SwKeN9EF0KNxpRwwJcDPkFxr_Fx0ykHb2Yl-r6w_xvAk4jH">