Name: ngR10089 Date: 02/26/2004



JLS, 2nd ed. doesn't contain documentation comment definition.
About traditional comment it says in 3.7 'Comments':

"/* text */ A traditional comment: all the text from the ASCII
                        characters /* to the ASCII characters */ is ignored
                        (as in C and C++)."

and

" Comment:
      TraditionalComment
      EndOfLineComment

  TraditionalComment:
      / * NotStar CommentTail
  . . ."

It is not clear should the compiler ignore the documentation comment or
it may report an error in the case when documentation comment is used
in the place where it is ignored by javadoc.

For example, the class

class test {
    int m (/** @deprecated comment's */ int j) {
        return j + 1;
    }
}

is not compiled by jdk1.5.0-b40:

test.java:6: modifier deprecated not allowed here
    int m (/** @deprecated comment's */ int j) {
                                          ^
1 error

althougt jdk1.5.0-b26 compiles this test successfully.

The specification is not clear. According to the first abstract this comment
should be ignored. The second abstract says that traditional comment cannot
begin with /** and compiler behaviour is not define in this case.


======================================================================