Community
Participate
Working Groups
There is nothing wrong with the sample class comment (javadoc generates the correct HTML without any warning or error): /** * Subclasses perform GUI-related work in a dedicated thread. For instructions * on using this class, see * {@link <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/threads.html"> Swing tutorial </a>} * * @see <a * href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intr o.html"> * EDU.oswego.cs.dl.util.concurrent </a> * @see <a * href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/package- summary.html"> * JDK 5.0 </a> * @author {@link <a href="http://gee.cs.oswego.edu/dl">Doug Lea</a>} * @author {@link <a href="http://home.pacbell.net/jfai">Jürgen Failenschmid</a>} */ Eclipse flags each line containing a href either with "Javadoc: Invalid URL link format" or "Javadoc: Invalid reference".
According to Javadoc spec 1.4, inline tag @link should be followed only with a reference then a label. String and URL link references are only specified for @see tag. However, if Javadoc can generate it without warning, I agree that we should not raise any for this kind of syntax...
Note that warnings in @see tags are due to the fact that <a> tag is declared on several lines. Again, as Javadoc accept this kind of syntax, we should not raise warnings on it...
The multi-line "<a href=" was created using the automatic formatter. However, Eclipse complains just the same if the link is on a single line, e.g.: {@link <a href="http://www.seas.ucla.edu/java3d/com/sun/j3d/utils/applet/JMainFrame.html" > JMainFrame </a>} Both cases are accepted by Javadoc.
As I said in comment 1, for @link inline tag, problem comes from a strict implementation of the Javadoc spec. Comment 2 was to say that multiline issue is only for @see tag...
*** Bug 76460 has been marked as a duplicate of this bug. ***
Fixed. Now string and URL link references are allowed for inline tags * {@link "string"} * {@link <a href="URL">text</a>} Note that it's still not allowed to add text after these kind of references. So, following syntaxes will be warned as invalid: * {@link "string"unexpected text} * {@link <a href="URL">text</a>unexpected text} It's also now possible to write an URL link reference tag on several line for @see tag. [jdt-core-internal] Changes done in AbstractCommentParser: parseHref() and parseReference() Test cases added in JavadocTestMixed
Please also verify that the fix is compatible with the default automatic formatter: use the examples that I supplied originally. Automatically format the code (CTL-SHF-F). The URL reference will be split into several lines.
I've already made this verification... This explains the sentence I wrote in comment 6: "It's also now possible to write an URL link reference tag on several line for @see tag." Moreover, the Javadoc in your initial example was already formatted... Usually, before saying fixed to a bug, we verify that our change effectively fixes the example given in the bug... Saying that, from this fix, the only thing user should not write on several line for URL link reference in @see tag is the end of the tag: </a>. That means that following URL link reference: * @see <a * href="http://...html"> * EDU.oswego.cs.dl.util.concurrent * < * /a> will be flagged as invalid although Javadoc does not warn user during generation. We decide not to have same behavior than Javadoc in this peculiar case because with this syntax, Javadoc automatically add closing tag </a> and you get an extra "</a>" in the text... which is obviously not correct.
Verified for 3.1M3 with build I20041102
