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

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 中提及，更不用说在不同类的 Javadoc 中提及了。 Javadoc 是为那些试图使用该方法的人准备的，而这些人通常不需要知道这些事情。当然，如果到期调整，您可以提及，但无需提及变量或具体如何完成。

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

/**
 * 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 中也很突出，但它不会链接到变量。

/**
 * 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 添加到该方法，然后在原始方法的 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);
}