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

Question

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

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

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

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

Answer 1

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

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

Answer 2

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

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

Answer 3

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

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

Пример с Солнца