[LLVMbugs] [Bug 13374] New: Incorrect parsing of Doxygen line comments

[bugzilla-daemon at llvm.org]

http://llvm.org/bugs/show_bug.cgi?id=13374

             Bug #: 13374
           Summary: Incorrect parsing of Doxygen line comments
           Product: clang
           Version: trunk
          Platform: Macintosh
        OS/Version: MacOS X
            Status: NEW
          Severity: normal
          Priority: P
         Component: -New Bugs
        AssignedTo: unassignedclangbugs at nondot.org
        ReportedBy: jonathan.sauer at gmx.de
                CC: gribozavr at gmail.com, llvmbugs at cs.uiuc.edu
    Classification: Unclassified


The following program results in warnings when compiled with clang r160248:

/////////////////////////////////////////
//MARK: SpecializedTemplate<int, bool>

/**
 * Bar. Bar bar bar.
 */
int bar();


///
// \param d

/// Doxygen comment here
int foo();


///
// \param d

// Non-Doxygen comment here
int baz();


///
// \param d
int xyzzy();


This results in:

$ ~/LLVM/build/Release+Asserts/bin/clang++ -Wdocumentation -c -v clang.cpp 
clang version 3.2 (trunk 160248)
Target: x86_64-apple-darwin10.8.0
Thread model: posix
[...]
clang.cpp:2:32: warning: HTML start tag prematurely ended, expected attribute
name or '>'
      [-Wdocumentation]
//MARK: SpecializedTemplate<int, bool>
                               ^
clang.cpp:11:11: warning: parameter 'd' not found in the function declaration
[-Wdocumentation]
// \param d
          ^
2 warnings generated.


1. The warning about the premature end of the HTML tag should be in warning
category documentation-html, I think, as it will generate false positives when
not using HTML tags at all: Every time a comment mentions a template including
parameters (as in case "bar"), the warning will be generated. Also, enclosing
placeholders in "<" and ">" seems to be a common practice which might result in
false positives as well (e.g. "<function call>").

2. It seems that clang treats line comments starting with only "//" instead of
"///" or "//!" as Doxygen comments, if the line before and after (not counting
empty lines) are Doxygen comments as well (case "foo"). It does not do this
when the line after is a normal line comment (case "baz") or the function the
comment is attached to (case "xyzzy").

According to http://www.stack.nl/~dimitri/doxygen/docblocks.html#specialblock
this is incorrect:

- Only lines starting with "///" or "//!" should be treated as Doxygen
comments.

- An empty line should end a Doxygen comment block (see case "foo").

-- 
Configure bugmail: http://llvm.org/bugs/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.