Подтвердить что ты не робот

Каков наилучший способ использования JavaDoc для документирования перечисления Java?

Я только начал использовать перечисления Java в своих собственных проектах (я должен использовать JDK 1.4 на работе), и я смущен относительно лучшей практики использования JavaDoc для перечисления.

Я обнаружил, что этот метод работает, но результирующий код немного не обновлен:

/**
* Doc for enum
*/
public enum Something {
/**
* First thing
*/
FIRST_THING,
/**
* Second thing
*/
SECOND_THING;
//could continue with more
}

Можно ли каким-либо образом разбить объявления перечисления на их собственные строки, не связывая их запятыми или это лучший подход для использования JavaDoc для перечисления?

4b9b3361

ОТВЕТЫ

Ответ 1

Чтобы ответить на первую часть вашего вопроса, вам нужно отделить каждое значение перечисления запятой. Насколько я знаю, нет никакого способа обойти это.

Лично у меня нет проблем с кодом, как вы его представили. Кажется, это совершенно разумный способ документировать перечисление для меня.

Ответ 2

Как отметил Майк, вам нужно разделить значения enum запятыми, и они должны быть первыми вещами, перечисленными в объявлении enum (переменные экземпляра, константы, конструкторы и методы могут следовать).

Я думаю, что лучший способ документировать перечисления похож на обычные классы: тип перечисления получает описание функции и роли перечисления в целом ( "Something values are used to indicate which mode of operation a client wishes..." ), и каждое значение перечисления получает описание Javadoc его назначение и функция ( "FIRST_THING indicates that the operation should evaluate the first argument first.." ).

Если описания значений перечисления коротки, вы можете поместить их в одну строку как /** Evaluate first argument first. */, но я рекомендую хранить каждое значение перечисления в своей собственной строке. Большинство IDE могут быть настроены так, чтобы автоматически форматировать их.