web-dev-qa-db-ja.com

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を使用するための最良のアプローチですか？

javaenumsjavadoc
48
MetroidFan2002

質問の最初の部分に答えるには、各列挙値をコンマで区切る必要があります。私の知る限り、それを回避する方法はありません。

個人的には、あなたが提示した方法でコードに問題はありません。私に列挙型を文書化するための完全に合理的な方法のようです。

31
Mike Deck

Mikeが述べたように、列挙値はコンマで区切る必要があり、列挙宣言に最初にリストされている必要があります（インスタンス変数、定数、コンストラクター、メソッドが続く場合があります）。

列挙型を文書化する最良の方法は、通常のクラスに似ていると思います。列挙型は、列挙型全体の機能と役割の説明を取得し（ "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. */として1行に配置することをお勧めしますが、各列挙値を独自の行に保持することをお勧めします。ほとんどのIDEは、この方法で自動的にフォーマットするように構成できます。

13
Dov Wasserman