Usage of see in JavaDoc

Question

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

User · Answer

The  see tag is a bit different than the  link tag  limited in some ways and more flexible in others   Different JavaDoc link types  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

User · Answer

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  Writing proper javadoc with  see   Java SE documentation   see

User · Answer

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

User · Answer

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

User · Answer

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

[java] Usage of @see in JavaDoc?

Examples related to java

Examples related to methods

Examples related to javadoc