在其他类中链接到方法的Javadoc

Question

目前我正在使用Javadoc语法引用其他类中的方法：

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

根据我所理解的文档，这是正确的做法。但现在来到有趣或者令人沮丧的部分。当我生成这个javadoc时，首先遇到了以下错误：

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()}

这个的生成HTML代码是：

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

当然，我没有链接。 有人可以告诉我发生了什么，并提供修复此问题的任何提示吗？

根据ASCII表，字符123和64分别代表{和@，那么为什么这些字符在语法正确的情况下不被视为有效，而文档却说它们是有效的？

- Robert

---

只是确认一下... 你有阅读Javadoc生成器文档吗？http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#link - Diogo Moreira

你在编写这个JavaDoc的类中导入了 com.my.package.Class 吗？看起来“找不到引用”的情况很奇怪。另一方面，我从未将它们结合使用过，但是 @see 和 @link 之间可能会发生冲突，考虑到 @see 生成自己的部分，这并不让我感到惊讶。 - Fritz

@DiogoMoreira - 不，我还没有了解过这个引擎，但我会去看看。 - Robert

@Gamb - 当然这不是我的实际Javadoc输入;-) 是的，所有的导入都已经就位。 - Robert

如果在您的javadoc中将裸超链接作为@see标记的值，将出现类似的错误。 在此情况下，请使用HTML锚元素将超链接包装起来以进行修复：/** @see <a href="http://example.com">Example</a> */。 - cyber-monk

Answer 1

在Javadoc标签@see中，您不需要使用@link；Javadoc会为您创建链接。请尝试。

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

这里有关于@see的更多信息。

- rgettman

---

谢谢您，我刚刚测试了这个解决方案，它很好用！但是我在很多地方都看到说应该使用“see”中的链接才能使其正常工作，所以有点奇怪... - Robert

您可以在Javadoc尚未转换为链接的其他位置中使用@link，例如在@param的描述中，在@return的描述中，在描述的主要部分中等。 - rgettman

当我刚尝试这个时，它将该方法显示为纯文本，而不像我的@see本地方法一样可点击。 - JesseBoyd

Answer 2

除了@see外，还有一种更通用的方式来引用另一个类，可能还包括该类的方法，即{@link somepackage.SomeClass#someMethod(paramTypes)}。这样做的好处是可以在javadoc描述中间使用它。

从javadoc文档（@link标签的描述）中得知：

此标签与@see非常相似-两者都需要相同的引用，并且接受package.class＃member和label的完全相同语法。主要区别是{@link}生成内联链接而不是将链接放置在“参见”部分中。此外，{@link}标记以花括号开头和结尾，以将其与其余内联文本隔离开来。

- Jérôme Beau

---

啊，关键是要使用井号而不是点！谢谢！ - SMBiggs

Answer 3

因此，解决原始问题的方法是您不需要在同一行上同时使用“@see”和“{@link...}”引用。 "@link"标记是自足的，并且如注所述，您可以将其放置在javadoc块中的任何位置。因此，您可以混合使用这两种方法：

/**
 * some javadoc stuff
 * {@link com.my.package.Class#method()}
 * more stuff
 * @see com.my.package.AnotherClass
 */

- Dave Hentchel

---

这应该是被接受的答案，因为其他两个答案没有表明'@link'或者'@see'需要在多行注释/** */中而不是单行。 - Stoycho Andreev

@Sniper，{@link} 在单行 Javadoc 注释中可以正常工作，您可能指的是它们无法与以 // 开头的注释一起使用的事实吗？/** */ 是 Javadoc，并且对于任何 Javadoc 函数都是必需的。 - Jase

是的，@Jase，我遇到了这个问题，注释需要使用/** */，而不是//。 - Stoycho Andreev

@Sniper 我认为这并不意味着这个答案一定会被接受，因为这是一个关于Javadoc的问题 - 人们通常应该知道 Javadoc 只能在 Javadoc 注释中使用。 - Jase

@Jase 我有点同意你的看法，但我认为像Stackoverflow这样的信息源需要通过示例来解释，而不是引用Oracle文档或其他不明确的文档。这个答案是唯一一个提供了示例的答案，前面两个答案都是引用。 - Stoycho Andreev