Javadoc link to method in other class

Delving into Javadoc Linking

When your Javadoc needs more context, consider using @see or {@link} annotations.

The difference between {@link} and @see

The {@link} is the inner workings of your Javadoc, the gummy bear in the candy jar:

/**
 * The magic happens in {@link OtherClass#method(String)}.
 */


The @see is like a heads-up to other resources:

/**
 * @see OtherClass#method(String)
 */


It creates an entry in the "See Also" section.

Syntax and best practices

Now, don’t get it twisted, syntax has its kinks. With overloaded methods and methods with parameters it’s always a good idea to list the full qualified type names:

/**
 * Calculations are handled by {@link com.example.util.UtilityClass#complexCalculation(java.util.List, int)}.
 */


Troubleshooting common issues

Faced with Javadoc generation errors such as illegal character or wrong method signatures? Rein in your syntax, method names, class names and parameters to stay clear of these pitfalls.

For a more readable Javadoc, use descriptive texts with your {@link}:

/**
 * When it comes to sorting, rely on the {@link java.util.Collections#sort(java.util.List) good 'ol sort}.
 */


Tips to enhance Javadoc linking

Smart embedding

Embed {@link} within your documentation text, but do it like a surgeon – precision is key:

/**
 * This method inherits traits from {@link OtherClass#similarMethod()} (quite the family, this code).
 */


Parameter specifics

When dealing with overloaded methods, spell out each parameter type:

/**
 * This method takes inspiration from {@link OtherClass#method(java.lang.String, int)}. Seems like fans aren't just for celebrities!
 */


Generics handling

Methods with generic types have their own syntax – a convention that embraces generics:

/**
 * Further processing is performed by {@link SomeClass#<T>method(java.util.List<T>, T)}. You guessed it, T is the star here!
 */


Examples for Javadoc clarity

Using illustrative examples in Javadoc can clarify use cases and provide valuable insights.

Coding snippets

Use <code> or <pre> tags for those bite-sized code samples:

/**
 * Kickstart the singleton as follows:
 * <pre>{@code
 * SingletonExample instance = SingletonExample.getTheOne();  // I'm the one!
 * }</pre>
 */


Highlight related methods

Shine a spotlight on related functionality or alternative fixes:

/**
 * @see OtherClass#similarMethod() if you can't resist exploring other ways.
 */


Marking deprecated methods

If a method is deprecated, give a shoutout to its successor:

/**
 * @deprecated
 * <p>Pass the baton to {@link NewClass#newMethod()}</p> Remember, out with the old, in with the new!
 */
