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 在引用另一个类时的用法。我说的是引用当前文档的一部分时的用法。因此，我为什么要询问 @throws 周围的引号

Answer 1

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

@see 参考

[...]

添加一个另见标题，其中包含指向参考的链接或文本条目。一个文档注释可以包含任意数量的@see 标签，它们都分组在同一个标​​题下。 [...]

表格 1.@see string 标签表格为 string 添加了一个文本条目。没有生成链接。 字符串是书籍或其他 URL 无法提供的信息参考。 [...]

[...]

表单 2。@see <a href="URL#value">label</a> 表单添加了一个链接，如 URL#value 所定义。 [...]

[...]

表单 3.@see package.class#member 标签表单添加一个链接，该链接带有指向指定名称的文档的可见文本标签在引用的 Java 语言中。 [...]

您似乎在询问表格 1，但表格 1 仍然是“链接”/参考。它只是不可点击，因为它引用了一本书或其他离线资源。

简而言之，您使用@see 提供对存在于其他地方（即当前方法/字段/类型的javadoc 之外）的材料的引用。

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

Answer 2

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

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

一般如果您希望读者/用户阅读更多内容以理解您的代码，请使用@see。由您（或者您的老师或您的老板）决定何时正是您使用@see。 但不要使用@see 来解释Java 或Javadoc 的一般工作方式（关键字如while、throws、extends、@param、...）或者对于可以放在另一个标签中的东西（在大多数情况下，其他标签指出特定的关系）。所以不要将@see 用于@param、@return……中必须（或已经存在）的东西。