Usage of @see in JavaDoc?
JavaMethodsJavadocJava Problem Overview
When do I use @see
when dealing with JavaDocs? What is its usage?
For example if MethodA
calls MethodB
then do I have to put @see
in MethodB
's javadoc and reference MethodA
because that is what called it, or do I have to put a reference to MethodB
from MethodA
because it's calling it. I've read the stuff about @see
on the Oracle website and it seems to me to be incredibly vague, it says it means "see also" but not really what that means!
Java Solutions
Solution 1 - Java
Yeah, it is quite vague.
You should use it whenever for readers of the documentation of your method it may be useful to also look at some other method. If the documentation of your methodA says "Works like methodB but ...", then you surely should put a link.
An alternative to @see
would be the inline {@link ...}
tag:
/**
* ...
* Works like {@link #methodB}, but ...
*/
When the fact that methodA calls methodB is an implementation detail and there is no real relation from the outside, you don't need a link here.
Solution 2 - Java
The @see
tag is a bit different than the @link
tag,
limited in some ways and more flexible in others.
The following examples are from Eclipse:
- Displays the member name for better learning, and is refactorable; the name will update when renaming by refactor
- Refactorable and customizable; your text is displayed instead of the member name
- Displays name, refactorable
- Refactorable, customizable
- A rather mediocre combination that is:
- Refactorable, customizable, and stays in the See Also section
- Displays nicely in the Eclipse hover
- Displays the link tag and its formatting when generated
- When using multiple
@see
items, commas in the description make the output confusing
- Completely illegal; causes unexpected content and illegal character errors in the generator
See the results below:
JavaDoc generation results with different link types
Best regards.
Solution 3 - Java
@see is useful for information about related methods/classes in an API. It will produce a link to the referenced method/code on the documentation. Use it when there is related code that might help the user understand how to use the API.
Solution 4 - Java
A good example of a situation when @see
can be useful would be implementing or overriding an interface/abstract class method. The declaration would have javadoc
section detailing the method and the overridden/implemented method could use a @see
tag, referring to the base one.
Related question: https://stackoverflow.com/questions/11121600/writing-proper-javadoc-with-see
Java SE documentation: @see
Solution 5 - Java
I use @see to annotate methods of an interface implementation class where the description of the method is already provided in the javadoc of the interface. When we do that I notice that Eclipse pulls up the interface's documentation even when I am looking up method on the implementation reference during code complete