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

    <tr>
        <th>Summary</th>
        <td>
            clang -Wdocumentation is too picky about empty paragraph
        </td>
    </tr>

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

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

    <tr>
      <th>Reporter</th>
      <td>
          gilles-peskine-arm
      </td>
    </tr>
</table>

<pre>
    Clang's `-Wdocumentation` diagnostic rejects `\param <name> {description}`, `\return {description}` and `\retval <value> {description}` (possibly more) when the `{description}` part is empty. However, the [Doxygen documentation](https://doxygen.nl/manual/commands.html#cmdretval) does not suggest that the `{description}` must not be empty, and the `doxygen` command does not complain.

I can see the point that empty documentation is not as good as non-empty documentation. However, [in the real world](https://github.com/Mbed-TLS/mbedtls/issues/6960), we have a code base with many `\retval ERROR_CODE` annotations with an empty description, where the details of the meaning of the error code in each function is not particularly important. Clang started to complain about this in version 15.0.0, so Clang 15 broke our build.

Small reproducer: `a.h`
```
/** \file a.h */

/** Do stuff.
 *
 * \param n
 * \return
 * \retval 42
 */
int foo(int n);
```

Compilation with clang 15.0.6 or `16.0.0 (++20230101052931+d408c34d1f58-1~exp1~20230101173033.495` (from http://apt.llvm.org/focal/):
```
clang-15 -Wdocumentation -c a.h
a.h:5:11: warning: empty paragraph passed to '\param' command [-Wdocumentation]
 * \param n
   ~~~~~~~^
a.h:6:11: warning: empty paragraph passed to '\return' command [-Wdocumentation]
 * \return
   ~~~~~~~^
a.h:7:13: warning: empty paragraph passed to '\retval' command [-Wdocumentation]
 * \retval 42
   ~~~~~~~~~^
3 warnings generated.
```

Clang 10.x through 14.x only warns about `\param` and `\return`, not `\retval`. Clang ≤9.x only warns about `\param`.

Desired behavior: `-Wdocumentation` does not result in warnings about empty paragraphs, at least not with `\retval`.

</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJycVt2O4jgTfRpzUyJKnD9ywQU_jb5P2tVIMyvt5aqSFIl3HDuyHWhu5tlXTgINPUyvelstcEK5fHzq-JTRWtEoojVLtyzdL3BwrTbrRkhJdtmT_S4ULdF0i1LXl_VOomoYzy2wLFz-Wetq6Eg5dEIrloVQC2yUtk5UYOhvqtwYyNJdjwY7YPFOYUcsfgGWb2uylRH9ODff-zi-m8MNucGop0GAqn6LOqH0WU8oh1-mBcZXvbZWlPICnTbEeAHnlhS4lsZUzyb1aBwIC9T17hLA__SZTmQ8xHFWut3r10tDCh5JSPeMr1rnesviDeMHxg_1FBgoyfihQzWgH1S661DVNmhdJxmPq66e9uPR1ZosKO3ADk1D1oFr0X0ItxusG2eUNEH2SD1V86QZhA-dV35bpNJdL1GogIV7Fm6mz_9DhQos0Zih10LNKMbsj7v2PPlEaKHRuvbfSqvlk8gHIlm6FVMRDKGEszayfkZgI1w7lEGlO8YPv5dUL__47ZvnsqTaScv4QVg7kB9khZdR4bOfCVo8ESBUuiYo0RKchWuhQ3V5VNDL169fvv61-7J_mQSm9ITWThNQXTd9R7tfoSUz0VOTQyEt6OP42BEqoZrrIxmjzYRCKCCsWjgOqrpnzqtNVINEIy8gul4bh8oFMB44sA6NoxqcvtUKsNSDr4iwPumJjPXpojQIg_EgWT1PjlIojf5OoAcD5SBk_VDnbx1KCYZ6o-uhIsPijScHg9ZTNAVm4fw_PfqibBjfAEt3RyEJMGhhfHW4z_wWt9dg3XA8zguPsbcR3OxBPb6cTOCnd75gCb_LdF3VK_SoNeMrP1JeBvH2-Q7Gz53ueiEnAY91rma-gjDIQBtPQ5R5Pr2DML5lfMtDHodRGIUpL-KI8W2dhKsqTuromK6W0Q967aMf16Aoj8M4DpIinV3oaHQHXts3aWPvAilPXaBNw_jhqKvRHEbsm6fYR5DLKIV39gvLytdhCvKDeJOyeBNFvqBnNF6Qfjgp2RPeGOxb6NHaSVqM59dSMJ7fbIKl2_dOn-4_Kh_Aj-mPpS_3cLL_AmcWwefwPCjnV3ByDyf-PJzRoj8L50G0N0R3mOIrCgsNKTLo6HZOn4p30moYvIJrjR6aFqIkeAWt5GVMZWeHuOu_P3VPT9LUdr0H3Vsiy8Kr-bAXzlYF2yTFv6d_cJY9WWGohpJaPAl9dZZn14ZrJzJkB-m8od3YmJZ5Vxc7djcHknBue-MBfr-DCceiXsd1ERe4oHWU5UmerOKsWLTrrIyqnIoV5ceYytUq5LzKC0yThMoIk2gh1tNR5lmUpjzJA8zCPMmjPE2wrjIiloTUoZC3M7wYO9E6C-MoXUgsSdrxasW5ojOMPzLO_U3LrP2cZTk0liWhFNbZtyxOOEnryY_en3NhwWkNvai-X56zsxiMXH_QQv0y89eyN9rf0x56qAf_TwAAAP__GMAmKQ">