[cfe-commits] A couple of issues for -Wdocumentation.

[Enea Zaffanella]

Hello.

We have run clang++ with -Wdocumentation on some of our source code to 
see how it was going (and it usefully reported a few doc issues that we 
have fixed).

Here I am reporting a couple of diagnostics that seem to be wrong.

The first example is:
======================
template <typename T>
struct A {
   /*!
     \param a  First param
     \param b  Second param
   */
   template <typename B>
   void foo(T a, B b);
};

template <>
template <typename B>
void A<int>::foo(int, B);
======================

which produces

$ clang++  -Wdocumentation -c bug.cc
bug.cc:4:12: warning: parameter 'a' not found
       in the function declaration [-Wdocumentation]
     \param a  First param
            ^
bug.cc:5:12: warning: parameter 'b' not found
       in the function declaration [-Wdocumentation]
     \param b  Second param
            ^
2 warnings generated.

Note that source locations point at the primary template, but the 
diagnostic is actually triggered by the explicit specialization (which 
is where the parameter names are missing).


The second issue has to do with the correct parsing of "paragraphs".
Several special commands (\brief, \note, \warning, \return, etc.) start 
a new documentation paragraph. Afaict, the paragraph ends when we find:
  a) the end of the documentation block; or
  b) a blank line; or
  c) another special command ***of those starting a new paragraph***.

It seems to me that clang is currently overshooting point c) in that it 
seems to close a paragraph as soon as finding *any* special command. 
However, there are commands (such as \ingroup, \ref, \f$, etc.) that are 
not meant to start a new paragraph. For instance:

=============================
/*! \brief \ingroup MyGroup
   My brief description.

   My longer description.

   \return
   \f$\sum_{i=0}^{n-1} a[i]\f$.
*/
int sum(int* a, int n);
=============================

$ clang++  -Wdocumentation -c bug1.cc
bug1.cc:1:11: warning: empty paragraph passed
       to '\brief' command [-Wdocumentation]
/*! \brief \ingroup MyGroup
     ~~~~~~^
bug1.cc:6:10: warning: empty paragraph passed
       to '\return' command [-Wdocumentation]
   \return
   ~~~~~~~^
2 warnings generated.


Note: the observations above are based on the "perceived" behavior of 
some version of doxygen; other users may interpret the warnings produced 
by clang as "the right thing".

Enea.