Как лучше всего использовать 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 для перечисления?


java enums javadoc
person MetroidFan2002    schedule 12.10.2008    source источник
comment
На самом деле, по крайней мере, для JDK1.7 (другие версии не тестировались) совершенно законно ставить запятую после каждого значения перечисления, включая последнее. Просто поставьте точку с запятой после последнего значения, и все в порядке. Это упрощает перемещение значений или добавление/удаление, не беспокоясь об использовании запятой или точки с запятой.   -  person Bart    schedule 14.11.2013

Ответы (3)


arrow_upward
32
arrow_downward

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

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

person Mike Deck    schedule 12.10.2008

arrow_upward
14
arrow_downward

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

Я думаю, что лучший способ документирования перечислений аналогичен обычным классам: тип перечисления получает описание функции и роли перечисления в целом ("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 можно настроить на автоматическое форматирование таким образом.

person Dov Wasserman    schedule 12.10.2008

arrow_upward
-3
arrow_downward

Существует онлайн-инструмент поиска кода Google: http://www.google.com/codesearch.

Я пытаюсь найти информацию, выполнив что-то вроде "lang:java public enum"

Пример от Sun

person anjanb    schedule 12.10.2008