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

[Dmitri Gribenko]

On Thu, Aug 16, 2012 at 9:24 AM, Enea Zaffanella <zaffanella at cs.unipr.it> wrote:
> 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).

Hi Enea,

Thank you for the feedback!

> $ 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).

Should be fixed in r162033.

> 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".

Doxygen has some inconsistent and documentation-contradicting
behaviors and I don't think we intend to be compatible in those corner
cases that Doxygen just happens to parse in some particular way.

Behavior of \ingroup that you see is explained by how we model the
\ingroup command: it is a block command (thus, it starts a new
paragraph), its argument is text after the command up to line end.
But we don't do any special semantic analysis for this command (that
is, groups are not implemented).

Looking at http://www.stack.nl/~dimitri/doxygen/grouping.html I see
that it was intended to use \ingroup on a separate line, so I don't
consider it a bug.

LaTeX formulae are different.  We model them as a "verbatim block" --
a sort of a block command, so it starts a paragraph.  Given your
example, we might want to introduce a "verbatim inline" command for
\f$...\f$.  I will look into it.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/