Как упомянуть переменную в методе в другом классе в Javadoc? - PullRequest
Новая
       9

Как упомянуть переменную в методе в другом классе в Javadoc?

0 голосов
/ 05 мая 2018

Я хочу упомянуть мою переменную newDate в 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());
        LocalDateTime newDate = LocalDateTime.now().plusHours(WebToken.EXPIRE_ADJUSTER);
        webtokenObj.setExpireDate(newDate);
        em.merge(webtokenObj);
    }

1 Ответ

0 голосов
/ 05 мая 2018

Как уже упоминалось, детали реализации, такие как переменная newDate, вообще не должны упоминаться в Javadoc - не в 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, чтобы она отображалась как код в сгенерированной HTML-документации или в подсказках Javadoc большинства IDE, а также выделяется в 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);
}
...