-
Bug
-
Resolution: Not an Issue
-
P4
-
None
-
1.1
-
generic
-
solaris_2.5.1
If javadoc detects a method containing a "throws" clause for which one or more
of the thrown exceptions is not documented with an @exception doc-comment tag,
it generates a warning message. Unfortunately, the message is somewhat
misleading at times since it only mentions the first of the exceptions for which
the doc-comment tag is missing. The current warning message reads:
Method <method signature>
declares that it throws class <exception name>,
but there is no corresponding @exception item
To be accurate, javadoc should either 1) generate a separate message for each
exception not documented, 2) list the names of all exceptions not documented
in the one message that it generates, or 3) generalize the message to name
the first and mention that there may be others. Of these, option 2 is my
preference; option 3 is clearly the easiest and quickest to implement, however.
While you're at it, please change the warning message to end with "@exception
tag." [note the period] rather than "@exception item".
of the thrown exceptions is not documented with an @exception doc-comment tag,
it generates a warning message. Unfortunately, the message is somewhat
misleading at times since it only mentions the first of the exceptions for which
the doc-comment tag is missing. The current warning message reads:
Method <method signature>
declares that it throws class <exception name>,
but there is no corresponding @exception item
To be accurate, javadoc should either 1) generate a separate message for each
exception not documented, 2) list the names of all exceptions not documented
in the one message that it generates, or 3) generalize the message to name
the first and mention that there may be others. Of these, option 2 is my
preference; option 3 is clearly the easiest and quickest to implement, however.
While you're at it, please change the warning message to end with "@exception
tag." [note the period] rather than "@exception item".