Bugzilla – Full Text Bug Listing
| Summary: | [javadoc] should not interpret contents of @see label | ||
|---|---|---|---|
| Product: | [Eclipse Project] JDT | Reporter: | Markus Keller <markus.kell.r> |
| Component: | Core | Assignee: | JDT-Core-Inbox <jdt-core-inbox> |
| Status: | CLOSED WONTFIX | QA Contact: | |
| Severity: | minor | ||
| Priority: | P5 | CC: | frederic_fusier, jerome_lanneluc, konigsberg |
| Version: | 3.4 | Keywords: | helpwanted |
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Windows XP | ||
| Whiteboard: | stalebug | ||
(In reply to comment #0) > I20071010-1200 > > Parse this class: > > /** > * @see java.util.List {@code List<String>} > */ > public class Try { } > > => Was: The TagElement for @see... contains 3 fragments: > [QualifiedName, TextElement, TagElement] > > => Expected: Only [QualifiedName, TextElement], since the whole label after the > QualifiedName should not be parsed further on (just split up into a TextElement > for each line). > > The Javadoc tool displays this as: > See Also: > {@code List<String>} > This is implemented like this since the beginning (e.g. 3.0)... Not sure, but I think I remember this was done to be able to easily find the positions of 'java.util.List' reference inside the @link tag in the following example: /** * @see java.util.List {@link java.util.List} */ public class Try { } Why do you want to change this now? But there's no point in resolving the @link (or any other inline tag) inside an @see (or an @link or @linkplain) tag, since it has no semantics! It's just plain text.
If the user writes:
/**
* @see java.util.List and {@link java.util.Map}
*/
... the Javadoc too does *not* transform @link into a link.
The output is:
See Also:
and {@link java.util.Map}
... or in HTML:
<DT><B>See Also:</B>
<DD><A HREF="<some link>" title="class or interface in java.util">
<CODE>and {@link java.util.Map}</CODE>
</A>
> Why do you want to change this now?
Because it's wrong, can confuse the user, and because I'm starting to add linkification in Javadoc tooltips and the Javadoc view, and thereby stumbled upon this inconsistency.
(In reply to comment #2) > But there's no point in resolving the @link (or any other inline tag) inside an > @see (or an @link or @linkplain) tag, since it has no semantics! It's just > plain text. > > If the user writes: > /** > * @see java.util.List and {@link java.util.Map} > */ > ... the Javadoc too does *not* transform @link into a link. > > The output is: > See Also: > and {@link java.util.Map} > ... or in HTML: > <DT><B>See Also:</B> > <DD><A HREF="<some link>" title="class or interface in java.util"> > <CODE>and {@link java.util.Map}</CODE> > </A> > Once again, this is an unspecified behavior of the Javadoc tool. The "spec" says: "This tag [@link] is valid in all doc comments: overview, package, class, interface, constructor, method and field, including the text portion of any tag (such as @return, @param and @deprecated)." Obviously, "any tag" is not 100% correct and it seems that @see should be excluded... > > > Why do you want to change this now? > > Because it's wrong, can confuse the user, and because I'm starting to add > linkification in Javadoc tooltips and the Javadoc view, and thereby stumbled > upon this inconsistency. > Agreed that this should be fixed. The Javadoc tool looks stable on this unspecified behavior through all versions from 1.4 to 1.6... > Once again, this is an unspecified behavior of the Javadoc tool. The "spec"
> says: "This tag [@link] is valid in all doc comments: overview, package, class,
> interface, constructor, method and field, including the text portion of any tag
> (such as @return, @param and @deprecated)."
Yup, the "spec" is rather slippery. However, one could argue that the "label" portion in an @see or @link tag should not be considered as a "text portion", but I would not want to take this to court ... ;-)
(In reply to comment #4) > Yup, the "spec" is rather slippery. However, one could argue that the "label" > portion in an @see or @link tag should not be considered as a "text portion", > but I would not want to take this to court ... ;-) > Agreed, it seems that there are three different kind of text: "text", "label" and "description". You surely discover an implicit specification for the label kind, thanks :-) I think this inconsistency should be fixed for 3.4 Tentatively targeting RC1 Actually we won't have time for 3.4. Deferring. Ownership has changed for the javadoc comments bugs, but I surely will not have enough time to fix your bug during the 3.5 development process, hence set its priority to P5. Please provide a patch if you definitely need the bug to be fixed in this version and I'll have a look at it... TIA *** Bug 258706 has been marked as a duplicate of this bug. *** See also the similar bug 206345. This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. As such, we're closing this bug. If you have further information on the current state of the bug, please add it and reopen this bug. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant. -- The automated Eclipse Genie. |
I20071010-1200 Parse this class: /** * @see java.util.List {@code List<String>} */ public class Try { } => Was: The TagElement for @see... contains 3 fragments: [QualifiedName, TextElement, TagElement] => Expected: Only [QualifiedName, TextElement], since the whole label after the QualifiedName should not be parsed further on (just split up into a TextElement for each line). The Javadoc tool displays this as: See Also: {@code List<String>}