什么是适当使用Javadoc的标签@see？ [重复]

This question already has an answer here:

这个问题在这里已有答案:

Usage of @see in JavaDoc? 4 answers

在JavaDoc中使用@see? 4个答案

I am looking for recommendations on the Javadoc tag usage in my code. I want to conform to the Javadoc style guides and whether or not the @see tag would be appropriate in this particular case.

我正在寻找有关我的代码中的Javadoc标记用法的建议。我希望符合Javadoc样式指南以及@see标记是否适合这种特殊情况。

An example of the code that I have made a Javadoc comment for

我为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.
 */

Would it be appropriate to use the following?

使用以下内容是否合适?

/**
 *
 * 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.
 */

Also, would the " '@throws' " be appropriate? Is it possible to remove the quote marks around it or would the javadoc not generate?

另外,“'@throws'”是否合适?是否可以删除它周围的引号或javadoc不生成?

EDIT

I am not asking about the usage of @see when referencing another class. I am talking about the usage when referencing a part of the current piece of documentation. Hence why I asked about the quotation marks around @throws

在引用另一个类时,我不是在询问@see的用法。我正在谈论引用当前文档的一部分时的用法。因此,为什么我询问@throws周围的引号

2 个解决方案

#1

I wouldn't add @see '@throws'. @throws is just a keyword that is used in the Javadoc (the user won't see a literal @throws in the final HTML-Javadoc anyways). You don't need to explain the working of Java or Javadoc in your documentation. You only need to explain the logic behind your code and what others should take into account when using your library or trying to understand your code. Someone who reads the Javadoc of your implementation is supposed to know how Java and Javadoc works!

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

Only use @see when your method highly depends on some other method or in some cases when fields/variables defined in some other class are used in your method without the user knowing it (it is not given as an argument). Or if your method/class is implementing or using an algorithm or some connotation (for example your class is a representation of the fibonnaci heap, use @see to add a reference to fibonnaci heaps).

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

In general use the @see if you want the reader/user to read something extra to understand your code. It is up to you (or maybe your teacher or your boss) to decide when precisely you use the @see. But don't use @see to explain the general working of Java or Javadoc (keywords like while, throws, extends, @param, ...) or for something that can be put in another tag (other tags in most cases point out a specific relation). So don't use @see for something that has to go (or already is) in the @param, @return, ... either.

一般情况下,如果您希望读者/用户阅读额外的内容以理解您的代码,请使用@see。您(或者您的老师或老板)可以决定何时使用@see。但是不要使用@see来解释Java或Javadoc的一般工作(像while,throws,extends,@ param,...这样的关键字)或者可以放在另一个标签中的东西(大多数情况下其他标签指出特定的关系)。因此,不要在@param,@ return,...中使用@see作为必须去(或已经存在)的东西。

#2

If you read the documentation, you'll find:

如果您阅读文档,您会发现:

@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. [...]

添加See Also标题,其中包含指向引用的链接或文本条目。文档注释可以包含任意数量的@see标记,这些标记都归入同一标题下。 [...]

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. [...]

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

[...]

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

表2. @see 标签表单添加了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. [...]

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

You seem to be asking about form 1, but form 1 is still a "link" / reference. It's just not clickable, since it's referencing a book or other off-the-web resource.

你似乎在问表单1,但表单1仍然是一个“链接”/参考。它只是不可点击,因为它引用了一本书或其他非网络资源。

In short, you use @see to provide a reference to material that exists elsewhere, i.e. outside the javadoc of the current method/field/type.

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

You don't use @see to refer to something in the same javadoc text. For one, the @see section will likely not even be where the @see tag is.

您不使用@see来引用同一个javadoc文本中的内容。首先,@ see部分甚至可能不是@see标签的位置。

#1

#2