Javadoc 的标签@see 的正确用法是什么？

Question

我正在寻找有关在我的代码中使用 Javadoc 标记的建议。我想遵守 Javadoc 样式指南以及 @see 标记是否适用于这种特殊情况。

我为

添加了 Javadoc 注释的代码示例

/**
 *
 * Will check if the given shader (vertex, fragment etc) compiled successfully!
 * 
 * If the compilation was successful, no change will happen and nothing will be returned.
 *
 * @throws RuntimeException
 *             if there is an error in compiling the shader.
 */

使用以下是否合适？

/**
 *
 * Will check if the given shader (vertex, fragment etc) compiled successfully!
 * 
 * If the compilation was successful, no change will happen and nothing will be returned.
 * 
 * @see '@throws' for information on a compile error
 *
 * @throws RuntimeException
 *             Thrown if there is an error in compiling the shader.
 */

此外，“'@throws'”是否合适？是否可以删除它周围的引号或者 javadoc 不会生成？

编辑

我不是在询问 @see 在引用另一个 class 时的用法。我说的是引用当前文档的一部分时的用法。因此，为什么我询问 @throws

周围的引号

Answer 1

如果您阅读 documentation，您会发现：

@see reference

[...]

Adds a See Also heading with a link or text entry that points to a reference. A documentation comment can contain any number of @see tags, which are all grouped under the same heading. [...]

Form 1. The @see string tag form adds a text entry for string. No link is generated. The string is a book or other reference to information not available by URL. [...]

[...]

Form 2. The @see <a href="URL#value">label</a> form adds a link as defined by URL#value. [...]

[...]

Form 3. The @see package.class#member label form adds a link with a visible text label that points to the documentation for the specified name in the Java Language that is referenced. [...]

你好像问的是表格 1，但表格 1 仍然是一个“link”/参考。它只是不可点击，因为它引用了一本书或其他离线资源。

简而言之，您使用 @see 来提供对存在于别处的 material 的引用，即在当前 method/field/type.

的 javadoc 之外

您不使用 @see 来引用同一 javadoc 文本中的内容。其一，@see 部分甚至可能不在 @see 标签所在的位置。

Answer 2

我不会添加 @see '@throws'。 @throws 只是 Javadoc 中使用的关键字（无论如何，用户不会在最终的 HTML-Javadoc 中看到文字 @throws ). 您无需在文档中解释 Java 或 Javadoc 的工作原理。您只需要解释代码背后的逻辑，以及其他人在使用您的库或试图理解您的代码时应该考虑的事项。阅读您实施的 Javadoc 的人应该知道 Java 和 Javadoc 是如何工作的！

仅当您的方法高度依赖于其他方法时或在某些情况下当您的方法中使用了其他 class 中定义的 fields/variables 而用户不知情时，才使用 @see （它没有作为参数给出）。或者，如果您的 method/class 正在实施或使用算法或某些含义（例如，您的 class 是斐波那契堆的表示，请使用 @see 添加对斐波那契堆的引用）。

一般来说，如果你想让 reader/user 阅读一些额外的东西来理解你的代码，请使用 @see。 这取决于你（或者也许您的老师或老板）来决定您何时使用 @see。 但不要使用 @see 来解释 Java 或 Javadoc 的一般工作原理（关键字如 while、throws, extends, @param, ...) 或者可以放在另一个标签中的东西 （大多数情况下其他标签指出特定关系).因此，不要将 @see 用于 @param、@return、...中必须（或已经存在）的内容。

Javadoc 的标签@see 的正确用法是什么？

What would be an appropriate usage of Javadoc's tag @see?

java

javadoc