9

I am trying to create javadoc for my client library. In MyOtherClass, I put the the below @see , and get warnings. MyOtherClass and MyClass both are in different packages, in the same project.

@see MyClass#Constructor(Type1 param1, Type2 param2)
warning - Tag @see: reference not found: MyClass#Constructor(Type1 param1, Type2 param2)

Then I tried

@see MyClass#MyClass(Type1 param1, Type2 param2) 
warning - Tag @see: reference not found: MyClass#MyClass(Type1 param1, Type2 param2)

Also tried

@see #MyClass(Type1 param1, Type2 param2)
warning - Tag @see: reference not found: MyOtherClass#MyClass(Type1 param1, Type2 param2)

I know I am missing something real silly here.

Siddharth
  • 9,349
  • 16
  • 86
  • 148
  • 4
    have you tried adding the package? `@see MyPackage.MyClass#Constructor(Type1, Type2)` – ma cılay Apr 02 '12 at 04:25
  • @user306848 please add a more detailed answer. It will help complete this question for other readers. – Siddharth Aug 11 '13 at 02:38
  • @Siddharth I've added a detailed answer below as I had this same issue earlier. If you are happy with it and think it would be of use to future readers it would be great if you could accept it. Thanks! – SteveMellross Mar 28 '14 at 05:45

1 Answers1

9

This is because the Javadoc needs to know the exact location of the class you are referencing to create a link to it. Simply add the package as was mentioned in a comment above.

@see mypackage.MyClass#Constructor(Type1 p1, Type2 p2)

The javadoc tool will allow you to take shortcuts as follows:

// For methods in the same class:
@see #Constructor(Type1 p1, Type2 p2)

// For methods in the same package:
@see MyClass#Constructor(Type1 p1, Type2 p2)

If you have a long package name and want to hide it you can use a label:

@see mypackage.MyClass#Constructor(Type1 p1, Type2 p2) MyClass#Constructor(Type1 p1, Type2 p2)

The above will display:

See Also: MyClass.Constructor(Type1 p1, Type2 p2)

See the Oracle documentation here for more on @see

Warning: If you use the code completion feature of some IDEs (E.g. Eclipse) for creating Javadoc comments it may add an import for the package you are referencing instead. While this may make your comments look cleaner by excluding the package name it is not good practice to add actual dependencies purely for documentation.
SteveMellross
  • 3,404
  • 2
  • 20
  • 18
  • I don’t think this warning is correct, as import is mainly syntactic sugar. Do you have a source to back this up? – Olivier Cailloux Apr 15 '21 at 18:48
  • Different authors and code styles disagree (strongly!) over whether to add an import for documentation purposes. I use this annotation: `@Retention(RetentionPolicy.SOURCE) @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD }) public @interface UsedInJavadocOnly { Class>[] value(); }` to make it so that I can get tools to stop complaining; it has *no* runtime overhead. – Donal Fellows Nov 15 '22 at 15:41