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

[Enea Zaffanella]

On 08/16/2012 08:35 PM, Dmitri Gribenko wrote:
> 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.

OK, this sounds reasonable (and the workaround is simple).

> 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

Fine.

Please do also consider the case of \ref commands: these provide 
hyperlinks to other sections of the documentation and hence it seems 
really strange that they start a new paragraph.

Enea.