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

如前所述，Javadoc中根本不应该提及像newDate变量这样的实现细节 - 不是在方法的Javadoc中，而是在不同类的Javadoc中更少。 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，但它不会链接到变量。

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

或者，您也可以创建另一种方法来创建带偏移量的新日期，将Javadocs添加到该方法，并链接到原始方法的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中的另一个类的方法中提及变量？

1 个答案: