如何在 javadoc 中的另一个 class 的方法中提及变量？

Question

我想在 javadoc 中提及我的 newDate 变量，但我做不到。无论如何要在方法中提及变量。

/**
     * 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());
        LocalDateTime newDate = LocalDateTime.now().plusHours(WebToken.EXPIRE_ADJUSTER);
        webtokenObj.setExpireDate(newDate);
        em.merge(webtokenObj);
    }

Answer 1

如前所述，像 newDate 变量这样的实现细节根本不应该在 Javadoc 中提及——不应该在方法的 Javadoc 中提及，更不用说在不同 class. Javadoc 是为那些试图使用方法的人准备的，这些人通常不需要知道那些东西。你可以提一下，当然，如果是到期调整，但是没有必要提变量或者具体是怎么做的。

相反，如果变量本身需要解释（对于未来的开发人员，包括您自己，想要更改方法本身），请添加一行注释来解释它的作用。

/**
 * 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);
}

如果您仍想在 Javadoc 中提及该变量，您可以使用 <code>newDate</code> 以便它在生成的 HTML 文档或大多数 IDE 的 Javadoc 工具提示中呈现为代码，并且在 Javadoc 中也很突出，但它不会 link 到变量。

/**
 * 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);
}

或者，您还可以创建另一种方法来创建带有偏移量的新日期，将 Javadoc 添加到该方法，然后 link 到原始方法的 Javadoc 中的该方法。

/**
 * 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 中的另一个 class 的方法中提及变量？

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

java

javadoc