JavaDoc @see for MyClass constructor returning a warning "reference not found"

Question

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.

Answer 1

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.