On 08/16/2012 08:35 PM, Dmitri Gribenko wrote: > On Thu, Aug 16, 2012 at 9:24 AM, Enea Zaffanella <[email protected]> > 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. _______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
