Как написать Javadoc свойств?

Вы можете включить закрытые члены при создании документации Javadoc (используя -private), а затем использовать @link для ссылки на это свойство полей.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

В качестве альтернативы, если вы не хотите создавать Javadoc для всех закрытых членов, вы можете заключить соглашение о документировании всех методов получения и использовать @link в установщиках.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}

Lombok - очень удобная библиотека для таких задач.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

Это все, что вам нужно! Аннотация @Getter создает метод получения для каждого частного поля и присоединяет к нему javadoc.

PS: в библиотеке есть много интересных функций, которые вы, возможно, захотите опробовать.

Я делаю и то, и другое, чему способствует автозаполнение Eclipse.

Сначала я документирую недвижимость:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Затем я копирую и вставляю это в геттер:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

В eclipse операторы @return имеют автозаполнение - поэтому я добавляю слово Gets, строчную букву «t» и копирую предложение со строчной буквой «t». Затем я использую @return (с автозаполнением Eclipse), вставляю предложение и затем прописываю букву T. Тогда это выглядит так:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Наконец, я копирую эту документацию в установщик:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Затем я изменяю его, и с помощью автозаполнения Eclipse вы можете получить не только тег @param, но и имя параметра:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Тогда я закончил. На мой взгляд, этот шаблон значительно упрощает, в конечном итоге, не только напоминать себе, что это свойство означает через повторение, но также упрощает добавление дополнительных комментариев к геттеру и сеттеру, если вы хотите добавить сторону эффекты (например, запрет на использование пустых свойств, перевод строк в верхний регистр и т. д.). Я исследовал создание плагина Eclipse для этой цели, но мне не удалось найти подходящую точку расширения для JDT, поэтому я сдался.

Обратите внимание, что предложение не всегда может начинаться с буквы T - просто первая буква должна быть не заглавной / рекапитализированной при вставке.

Я действительно думаю, что это проблема, и официальное руководство по Javadoc ничего об этом не говорит. C # может решить эту проблему элегантным способом с использованием свойств (я не кодирую на C #, но я действительно думаю, что это хорошая функция).

Но у меня есть предположение: если вам нужно объяснить, что такое someString, возможно, это `` плохая мелочь '' в вашем коде. Это может означать, что вы должны написать SomeClass для ввода someString, чтобы вы объяснили, что такое someString в документации SomeClass, и просто чтобы javadocs в getter / setter не понадобились.