136

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!

OLIVER.KOO
  • 5,654
  • 3
  • 30
  • 62
Jeff
  • 2,017
  • 3
  • 15
  • 8
  • 5
    _put `@see` in `MethodB`'s javadoc and reference `MethodA` because that is what called it_ --> How would be ever possible to know all methods which call one of your methods ? Even if this is possible (say a private method used only once) linking from callee to caller sounds at least weird... – Mr_and_Mrs_D Sep 20 '13 at 13:39
  • 1
    It means what it usually means in English: https://www.oxforddictionaries.com/us/definition/american_english/see (definition 1.4) – stackexchanger Aug 23 '16 at 15:30

5 Answers5

146

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.

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210
  • 19
    `@see` is also useful for linking to alternatives to `@Deprecated` methods. – Mark Peschel May 30 '17 at 00:11
  • 2
    @MauveRanger Since `@see` is pretty vague, for deprecated stuff I find it more useful to do something more explicit, like: `@deprecated since X.Y.Z; use {@link #alternateMethod()} instead` – Christopher Jan 10 '20 at 00:10
23

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:

different JavaDoc link types Different JavaDoc link types

  1. Displays the member name for better learning, and is refactorable; the name will update when renaming by refactor
  2. Refactorable and customizable; your text is displayed instead of the member name
  3. Displays name, refactorable
  4. Refactorable, customizable
  5. 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
  1. Completely illegal; causes unexpected content and illegal character errors in the generator

See the results below:

JavaDoc generation results with different link types JavaDoc generation results with different link types

Best regards.

nikodaemus
  • 1,918
  • 3
  • 21
  • 32
  • 3
    +1 for listing the different possibilities to use links in javadoc with examples. But note that other JavaDoc renderers will behave different! 5. does not work with IntelliJ, for example. – Qw3ry Apr 13 '21 at 08:55
13

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

Community
  • 1
  • 1
AtomHeartFather
  • 954
  • 17
  • 35
  • 2
    wasn't me, but it was probably because we have @inheritDoc http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc –  Nov 05 '14 at 17:04
  • 1
    the java documentation for @see is a really good. should be first. – dok Aug 04 '16 at 11:44
  • 2
    @vaxquis `@inheritDoc` copies the documentation from another location. I imagine that describing details rather than adding fluff has its uses? – Nielsvh Feb 01 '17 at 22:17
  • @Nielsvg this answer mentions that `the overridden/implemented method could use a @see tag, referring to the base one.` - and that's exactly what `@inheritDoc` is for; IMO it's better to include the base class description verbatim by means of `@inheritDoc` *and* supplement it as needed, than to refer to it by `@see` - see (sic!) http://stackoverflow.com/questions/11121600/writing-proper-javadoc-with-see ; many developers (me included) prefer having *all* the implementation details in one place, instead of neverending chain of upwards links leading upwards through an inheritance hierarchy. –  Feb 01 '17 at 22:35
12

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

Rob Dawson
  • 1,349
  • 10
  • 21
3

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

Maruthi
  • 460
  • 4
  • 11