Bug ID: JDK-8007644 Javadoc tag @exception for unchecked exceptions is broken till from 1.8.0-b75

Test name: nsk/regression/b4253260   execute_positive    quick,regression,jdk


Java doc specification: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#throwstag

Java code looks like     /**
     * Compares this Byte to another Object.  If the Object is a Byte,
     * this function behaves like <code>compareTo(Byte)</code>.  Otherwise,
     * it throws a <code>ClassCastException</code> (as Bytes are comparable
     * only to other Bytes).
     *
     * @param   o the <code>Object</code> to be compared.
     * @return  the value <code>0</code> if the argument is a Byte
     *          numerically equal to this Byte; a value less than
     *          <code>0</code> if the argument is a Byte numerically
     *          greater than this Byte; and a value greater than
     *          <code>0</code> if the argument is a Byte numerically
     *          less than this Byte.
     * @exception <code>ClassCastException</code> if the argument is not a
     *            <code>Byte</code>.
     * @see     java.lang.Comparable
     * @since   1.2
     */
    public int compareTo(Object o) {
        return compareTo((Byte)o);
    }

It passed in JDK7 and JDK8 b74 
but fails in JDK8 b75 with error 

[2013-02-06T05:39:51.62] /export/local/aurora/sandbox/results/ResultDir/b4253260/java/lang/Byte.java:258: error: unexpected text
[2013-02-06T05:39:51.62]      * @exception <code>ClassCastException</code> if the argument is not a
[2013-02-06T05:39:51.62]        ^

Thanks for update
08-02-2013
At the last I got it! Thanks. Bent have opened new CR against this test https://jbs.oracle.com/bugs/browse/INTJDK-7601881.
08-02-2013
I will grant you one point. The caret in the error message is not pointing at the most helpful position. [2013-02-06T05:39:51.62] /export/local/aurora/sandbox/results/ResultDir/b4253260/java/lang/Byte.java:258: error: unexpected text [2013-02-06T05:39:51.62] * @exception <code>ClassCastException</code> if the argument is not a [2013-02-06T05:39:51.62] ^ The unexpected text is the <code>, so it would be better if the caret were pointing directly at that, and not at @exception. And, sigh, the message does not display correctly here in the comment, because spaces get compressed in the display. See the occurrence of this message in the original log for the exact display.
07-02-2013
You have completely missed the point. <code>ClassCastException</code> is NOT a valid Java name for an exception. You need to remove the enclosing <code>...</code> from the name of the exception.
07-02-2013
Jonathan, I am confused. 1) Let take http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#throws It says "The @throws and @exception tags are synonyms. Adds a "Throws" subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that may be thrown by the method. This tag is valid only in the doc comment for a method or constructor. If this class is not fully-specified, the Javadoc tool uses the search order to look up this class. Multiple @throws tags can be used in a given doc comment for the same or different exceptions. To ensure that all checked exceptions are documented, if a @throws tag does not exist for an exception in the throws clause, the Javadoc tool automatically adds that exception to the HTML output (with no description) as if it were documented with @throws tag. The @throws documentation is copied from an overridden method to a subclass only when the exception is explicitly declared in the overridden method. The same is true for copying from an interface method to an implementing method. You can use {@inheritDoc} to force @throws to inherit documentation. For more details, see writing @throws tags." 2) Let follow link -> writing @throws tags. And I am on the page "http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@exception" which says: "A @throws tag should be included for any checked exceptions (declared in the throws clause), as illustrated below, and also for any unchecked exceptions that the caller might reasonably want to catch, with the exception of NullPointerException. Errors should not be documented as they are unpredictable. For more details, please see Documenting Exceptions with the @throws Tag." 3) Then let follow link -> see "Documenting Exceptions with the @throws Tag." Then here you can read "Those unchecked exceptions that the caller might reasonably want to catch. (It is considered poor programming practice to include unchecked exceptions in the throws clause.) Documenting these in the @throws tag is up to the judgment of the API designer, as described below. Documenting Unchecked Exceptions It is generally desirable to document the unchecked exceptions that a method can throw: this allows (but does not require) the caller to handle these exceptions. For example, it allows the caller to "translate" an implementation-dependent unchecked exception to some other exception that is more appropriate to the caller's exported abstraction. Since there is no way to guarantee that a call has documented all of the unchecked exceptions that it may throw, the programmer must not depend on the presumption that a method cannot throw any unchecked exceptions other than those that it is documented to throw. In other words, you should always assume that a method can throw unchecked exceptions that are undocumented. Note that it is always inappropriate to document that a method throws an unchecked exception that is tied to the current implementation of that method. In other words, document exceptions that are independent of the underlying implementation. For example, a method that takes an index and uses an array internally should not be documented to throw an ArrayIndexOutOfBoundsException, as another implementation could use a data structure other than an array internally. It is, however, generally appropriate to document that such a method throws an IndexOutOfBoundsException. Keep in mind that if you do not document an unchecked exception, other implementations are free to not throw that exception. Documenting exceptions properly is an important part of write-once, run-anywhere." Is it outdated documentation? There a no word about backward compatibility, and changed behavior. Then. Let start this test against 7u14b12 - Test passes!! -sh-3.2$ bash check.sh Loading source files for package java.lang... Constructing Javadoc information... Standard Doclet version 1.7.0_14-ea Building tree for all the packages and classes... Generating /export/local/tmp/results/ResultDir/b4253260/java/lang/Boolean.html... Generating /export/local/tmp/results/ResultDir/b4253260/java/lang/Byte.html... Generating /export/local/tmp/results/ResultDir/b4253260/java/lang/package-frame.html... Generating /export/local/tmp/results/ResultDir/b4253260/java/lang/package-summary.html... Generating /export/local/tmp/results/ResultDir/b4253260/constant-values.html... Generating /export/local/tmp/results/ResultDir/b4253260/serialized-form.html... Building index for all the packages and classes... Building index for all classes... Generating /export/local/tmp/results/ResultDir/b4253260/allclasses-frame.html... Generating /export/local/tmp/results/ResultDir/b4253260/allclasses-noframe.html... Generating /export/local/tmp/results/ResultDir/b4253260/index.html... -sh-3.2$ /java/re/jdk/1.7.0_14/promoted/all/b12/binaries/linux-i586/ bin/ db/ demo/ fastdebug/ include/ jre/ lib/ man/ sample/ -sh-3.2$ /java/re/jdk/1.7.0_14/promoted/all/b12/binaries/linux-i586/bin/java -version java version "1.7.0_14-ea" Java(TM) SE Runtime Environment (build 1.7.0_14-ea-b12) Java HotSpot(TM) Client VM (build 24.0-b30, mixed mode) So I am reopening bug.
07-02-2013
See this part of the spec: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#throws The first arg is a simple "classname".
06-02-2013
Javadoc is behaving correctly. The tag spac does not permit the use of HTML tags, such as <ode>...</code> for the argument of @execption and @throws. This is but one of the many new validity checks performed by the new doclint feature, which is enabled by default in javadoc. To get rid of the message, fix the source code or use -Xdoclint:none to disable doclint.
06-02-2013