321

Currently I'm referencing methods in other classes with this Javadoc syntax:

@see {@link com.my.package.Class#method()}

And in what I understand from the documentation this is the correct way to do this. But now to the funny part, or frustrating. When I generate this javadoc I first of all get following error:

warning - Tag @see:illegal character: "123" in "{@link com.my.package.Class#method()}"
warning - Tag @see:illegal character: "64" in "{@link com.my.package.Class#method()}"
warning - Tag @see: reference not found: {@link com.my.package.Class#method()}

The Generated HTML code of this is:

"," <code>com.my.package.Class#method()}</code> ","

And of course I have no link. Can anyone tell me what's happening, and any hints on how to fix this?

According to the ASCII table characters 123 and 64 for wold represent { and @, so why aren't these characters valid when this syntax is correct according to the documentation?

Robert
  • 4,602
  • 4
  • 22
  • 33
  • 1
    Just to check... have you read the Javadoc Generator documentation? http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#link – Diogo Moreira Jul 05 '13 at 19:58
  • Did you import `com.my.package.Class` in the class this JavaDoc is written? The _reference not found_ seems odd. On the other hand, I've never used them combined but there's a chance that `@see` and `@link` conflict with each other, taking that `@see` generates its own seciton it wouldn't surprise me. – Fritz Jul 05 '13 at 20:07
  • 1
    @DiogoMoreira - No I havn't read about the engine, but I will check it out. – Robert Jul 05 '13 at 20:17
  • @Gamb - Of course it's not my actual Javadoc input;-) Yes all imports are in place. – Robert Jul 05 '13 at 20:18
  • 1
    A similar error occurs if you put a raw hyperlink as the value for the `@see` tag in your javadoc. To fix it in this case wrap the hyperlink in an html anchor element: `/** @see Example */` – cyber-monk Jul 31 '15 at 23:14

3 Answers3

374

For the Javadoc tag @see, you don't need to use @link; Javadoc will create a link for you. Try

@see com.my.package.Class#method()

Here's more info about @see.

rgettman
  • 176,041
  • 30
  • 275
  • 357
  • Thanks for this, I just tested this solution and this works fine! But I've read in so many places that you should use the link in see to get this to work, so that's a bit strange... – Robert Jul 05 '13 at 20:20
  • 8
    You can use `@link` in other places that Javadoc doesn't already turn into a link, e.g. in the description for `@param`, in the description for `@return`, in the main part of the description, etc. – rgettman Jul 05 '13 at 20:21
  • 2
    when I just tried this it displays the method as plain text it is not clickable like my @see for a local method. – JesseBoyd Jul 14 '17 at 16:05
205

Aside from @see, a more general way of refering to another class and possibly method of that class is {@link somepackage.SomeClass#someMethod(paramTypes)}. This has the benefit of being usable in the middle of a javadoc description.

From the javadoc documentation (description of the @link tag):

This tag is very simliar to @see – both require the same references and accept exactly the same syntax for package.class#member and label. The main difference is that {@link} generates an in-line link rather than placing the link in the "See Also" section. Also, the {@link} tag begins and ends with curly braces to separate it from the rest of the in-line text.

Ilya Serbis
  • 21,149
  • 6
  • 87
  • 74
Jérôme Beau
  • 10,608
  • 5
  • 48
  • 52
110

So the solution to the original problem is that you don't need both the "@see" and the "{@link...}" references on the same line. The "@link" tag is self-sufficient and, as noted, you can put it anywhere in the javadoc block. So you can mix the two approaches:

/**
 * some javadoc stuff
 * {@link com.my.package.Class#method()}
 * more stuff
 * @see com.my.package.AnotherClass
 */
Dave Hentchel
  • 1,141
  • 1
  • 8
  • 2
  • 7
    This should be accepted answer because other two answers don't show that '@link' or '@see' need to be in multiple row comment /** */ not single row – Stoycho Andreev May 31 '17 at 10:14
  • 1
    @Sniper, `{@link }` works fine in a single-row Javadoc comment, are you perhaps referring to the fact that they don't work with comments starting with `//`? `/** */` is Javadoc and is necessary for any Javadoc functions. – Jase Jun 13 '17 at 04:58
  • Yes @Jase I met exactly this the comment needs to be /** */, but not // – Stoycho Andreev Jun 13 '17 at 08:01
  • 7
    @Sniper I don't think that necessitates this being the accepted answer because this is a Javadoc question to begin with - it should be generally understood that Javadoc only works in Javadoc comments. – Jase Jun 14 '17 at 01:37
  • @Jase kind of agree with you, but I believe that source of information like Stackoverflow needs explanations by examples not quotes from the Oracle documentation or some other documentation, which is not clear obviously. This answer is the only answer who has example, above two answers are quotes. – Stoycho Andreev Jun 14 '17 at 10:05