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

Question

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.

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

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

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

Answer 1

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

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

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.

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.

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.

Answer 2

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!

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).

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.