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

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

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

一般来说如果您希望读者/用户阅读额外的内容以了解您的代码，请使用@see。由您（或者您的老师或老板）来决定决定何时使用@see。 但请勿使用@see来解释Java或Javadoc的常规工作（while，throws，extends，{{1}等关键字}}，...）或者可以放在另一个标记中的东西（在大多数情况下，其他标记指出特定的关系）。因此，请不要将@param用于@see，@param，......之内必须（或已经存在）的内容。

Answer 2

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

@see 参考

[...]

使用 指向参考 的链接或文本条目添加另请标题。文档注释可以包含任意数量的@see标记，这些标记在同一标题下都是分组。 [...]

表单1。 @see string标记表单为字符串添加了一个文本条目。没有生成链接。 该字符串是书籍或其他对URL不可用的信息的引用。 [...]

[...]

表单2。 @see <a href="URL#value">label</a>表单 添加URL#value定义的链接 。 [...]

[...]

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

您似乎在询问表单1，但表单1仍然是＆＃34;链接＆＃34; /参考。它只是不可点击，因为它引用了一本书或其他非网络资源。

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

您不能使用@see来引用相同javadoc文本中的内容。例如，@see部分甚至可能不在@see标记的位置。

什么是Javadoc的标签@see的适当用法？

2 个答案: