链接到 Javadoc 中的外部 URL？答案

【问题标题】：Linking to an external URL in Javadoc?链接到 Javadoc 中的外部 URL？
【发布时间】：2010-11-08 02:21:03
【问题描述】：

类似：

/**
 * See {@linktourl http://google.com}
 */

【问题讨论】：

标签： java url javadoc hyperlink

【解决方案1】：

这会创建一个包含链接的“另见”标题，即：

/**
 * @see <a href="http://google.com">http://google.com</a>
 */

将呈现为：

另请参阅：
http://google.com

而这个：

/**
 * See <a href="http://google.com">http://google.com</a>
 */

将创建一个内嵌链接：

见http://google.com

【讨论】：

如果有人有兴趣，因为我只需要查一下：根据Javadoc spec @see 标签在之后 @param/@return标签和 before @since/@serial/@deprecated 标签。
以防万一，Intellij 13 似乎不支持这个标签。它确实支持内联链接。该标签是否已被弃用？
我推荐<a href="http://google.com" target="_top">http://google.com</a>. 添加target="_top" 的原因是因为一些生成的javadoc html文件使用了框架，您可能希望导航影响整个页面而不仅仅是当前帧。
如果您收到类似“警告 - 标记 \@see: missing final '>':”的警告，请确保在同一 \@see 指令中没有两个超链接。相反，每个 \@see 使用一个链接。
为什么将 URL 链接添加到 javadoc 如此复杂？谁认为 HTML 是个好主意... /facepalm

【解决方案2】：

很难从 Oracle 网站找到明确的答案。以下来自javax.ws.rs.core.HttpHeaders.java：

/**
 * See {@link <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">HTTP/1.1 documentation</a>}.
 */
public static final String ACCEPT = "Accept";

/**
 * See {@link <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.2">HTTP/1.1 documentation</a>}.
 */
public static final String ACCEPT_CHARSET = "Accept-Charset";

【讨论】：

用{@link ...}包裹<a> html标签有什么意义？
这可能是一个错误，因为the javadoc documentation 没有提到这种形式，因为它与原始的<a> 没有区别。
这里的 {@link xxx} 不对。 {@link xxx} 用于链接到源代码中的其他类和方法。这里没有必要。其余的都很好。
Java 8 标准不允许这种结构（doclint on）。
这是完全错误的。根据reference 和documentation 的正确用法是{@link package.class#member label}

【解决方案3】：

Javadocs 不为外部链接提供任何特殊工具，因此您应该只使用标准 html：

See <a href="http://groversmill.com/">Grover's Mill</a> for a history of the
Martian invasion.

或

@see <a href="http://groversmill.com/">Grover's Mill</a> for a history of 
the Martian invasion.

不要使用{@link ...} 或{@linkplain ...}，因为它们用于链接到其他类和方法的javadocs。

【讨论】：

【解决方案4】：

取自javadoc spec

@see <a href="URL#value">label</a> : 添加由URL#value 定义的链接。 URL#value 是相对或绝对 URL。 Javadoc 工具通过查找小于号 (<) 作为第一个字符来将此与其他情况区分开来。

例如：@see <a href="http://www.google.com">Google</a>

【讨论】：

奇怪；我发誓我只添加了反引号；不知道例子跑到哪里去了……
我认为我们遇到了某种并发编辑问题。我也把它们放进去。
很公平。但是，您在块引用的第一行中缺少反引号....
@see 不是必需的。 javadocs可以用html标签格式化，所以只需要“a”标签。
@GabrielLlamas 是的，但最初的问题暗示这就是它的使用方式。知道它具体确实在另见领域中工作很有用，这是很多人想要的。