JavaDoc @see为MyClass构造函数返回警告“未找到引用”

Question

我正在尝试为我的客户端库创建javadoc。在MyOtherClass中，我把下面的@see，并得到警告。 MyOtherClass和MyClass都在不同的包中，在同一个项目中。

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

然后我试了

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

也试过

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

我知道我在这里错过了一些真正愚蠢的东西。

Answer 1

这是因为Javadoc需要知道您引用的类的确切位置以创建指向它的链接。只需添加上面评论中提到的包。

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

javadoc工具允许您按如下方式选择快捷方式：

// 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)

如果您有一个较长的包名并想隐藏它，您可以使用标签：

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

以上将显示：

另请参阅： MyClass.Constructor(Type1 p1, Type2 p2)

有关@see的更多信息，请参阅Oracle文档here

<小时/> 警告：如果您使用某些IDE（例如Eclipse）的代码完成功能来创建Javadoc注释，则可能会为您引用的包添加导入。虽然这可以通过排除包名称使您的注释看起来更清晰，但是纯粹为文档添加实际依赖项并不是一个好习惯。