How to Reference a Method in Javadoc

How to reference a method in javadoc?

You will find much information about JavaDoc at the Documentation Comment Specification for the Standard Doclet, including the information on the

{@link module/package.class#member label}

tag (that you are looking for). The corresponding example from the documentation is as follows

For example, here is a comment that refers to the getComponentAt(int, int) method:

Use the {@link #getComponentAt(int, int) getComponentAt} method.

The module/package.class part can be ommited if the referred method is in the current class.

---

Other useful links about JavaDoc are:

• JDK 17 Tool Specifications - The javadoc Command
• JavaDoc Guide
• How to Write Doc Comments for the Javadoc Tool

How to add reference to a method parameter in javadoc?

As far as I can tell after reading the docs for javadoc there is no such feature.

Don't use <code>foo</code> as recommended in other answers; you can use {@code foo}. This is especially good to know when you refer to a generic type such as {@code Iterator<String>} -- sure looks nicer than <code>Iterator<String></code>, doesn't it!

How to reference another method of the same class in Javadoc?

Use the @link inline tag, and refer to the method with a leading #.

/**
 * ...
 * This method is similar to {@link #contains()}, with the following differences:
 * ...
 */
public boolean containsSame();

/**
 * This method does ...
 */
public boolean contains();

This example only works if there is actually a contains() method which has no arguments (which, actually, seems to be not that useful). If you have only a contains method with arguments, then either write the argument types in the parentheses:

/**
 * ...
 * This method is similar to {@link #contains(Element)}, with the following differences:
 * ...
 */
public boolean containsSame(Element e);

/**
 * This method does ...
 */
public boolean contains(Element e);

Or you can omit the parentheses completely:

/**
 * ...
 * This method is similar to {@link #contains}, with the following differences:
 * ...
 */
public boolean containsSame(Element e);

/**
 * This method does ...
 */
public boolean contains(Element e);

If you have several methods named contains (with different parameter lists), this version can't decide which one to use (the link will jump to any of them, hopefully they are all together and do similar things).

Refactorable reference to a method parameter in javadoc

Due to Java erasure, method argument names are ephemeral, they are not part of the static class definition. So, void foo(int p) being changed to void foo(int x) is not considered refactoring, because it is guaranteed that it will not affect the program's logic in any way (unless the argument is overloading a class field).

So in the javadoc there cannot be a static link that identifies the method argument. The mere fact that the word after @param changes when you refactor the method is a favor offered by the IDE.

how to mention a variable within a method in another class in javadoc?

As already mentioned, implementation details like the newDate variable should not be mentioned in the Javadoc at all -- not in the Javadoc of the method, and much less in the Javadoc of a different class. The Javadoc is for folks trying to use the method, and those usually don't need to know those things. What you can mention, of course, if the expiration adjustment, but there's no need to mention the variable or how exactly it's done.

Instead, if the variable itself needs explaining (for future developers, including yourself, wanting to change the method itself), add a line comment explaining what it does.

/**
 * Extends duration of a webToken {@link de.core.model.security.WebToken}.
 *
 * @param webToken to extend webtokens duration.
 */
public void extendDuration(@NonNull WebToken webToken) {
    WebToken webtokenObj = getWebToken(webToken.getToken());
    // the significance of the variable is ...
    LocalDateTime newDate = LocalDateTime.now().plusHours(WebToken.EXPIRE_ADJUSTER);
    webtokenObj.setExpireDate(newDate);
    em.merge(webtokenObj);
}

If you still want to mention the variable in the Javadoc, you could use <code>newDate</code> so it is rendered as code in the generated HTML documentation, or in the Javadoc tooltips of most IDEs, and also stands out in the Javadoc, but it will not link to the variable.

/**
 * Extends duration of a webToken {@link de.core.model.security.WebToken}.
 * 
 * The <code>newDate</code> variable defines ...
 *
 * @param webToken to extend webtokens duration.
 */
public void extendDuration(@NonNull WebToken webToken) {
    WebToken webtokenObj = getWebToken(webToken.getToken());
    LocalDateTime newDate = LocalDateTime.now().plusHours(WebToken.EXPIRE_ADJUSTER);
    webtokenObj.setExpireDate(newDate);
    em.merge(webtokenObj);
}

Alternatively, you could also create another method for creating the new date with the offset, add Javadocs to that method, and link to that method in the Javadoc of your original method.

/**
 * Extends duration of a webToken {@link de.core.model.security.WebToken}.
 * 
 * @see TheClass#createNewDate
 *
 * @param webToken to extend webtokens duration.
 */
public void extendDuration(@NonNull WebToken webToken) {
    WebToken webtokenObj = getWebToken(webToken.getToken());
    webtokenObj.setExpireDate(newDate);
    webtokenObj.setExpireDate(createNewDate());
    em.merge(webtokenObj);
}

/**
 * add useful Javadoc here
 */
public LocalDateTime createNewDate() {
    return LocalDateTime.now().plusHours(WebToken.EXPIRE_ADJUSTER);
}

Javadoc @see or {@link}?

The official guidelines on this are pretty clear.

The functional differences are:

• {@link} is an inline link and can be placed wherever you like
• @see creates its own section

In my opinion, {@link} is best used when you literally use a class, field, constructor or method name in your description. The user will be able to click through to the javadoc of what you've linked.

I use the @see annotation in 2 cases:

• Something is very relevant but not mentioned in the description.
• I refer to the same thing multiple times in the description, and it is used as a replacement for multiple links to the same.

I based this opinion on randomly checking out documentation for a great variety of things in the standard library.

---

Related Topics