Javadoc：package.htmlまたはpackage-info.java

230

パッケージレベルのJavadocコメントを作成する場合、推奨される方法は何ですか。職業はなんですか？

package-info.java

長所
- 新しい
短所
- クラスの乱用-クラスはコメント用ではなくコード用です

package.html

長所
- HTML拡張はそのコードではないことを意味します
- IDE /テキストエディターでの構文の強調表示
短所
- なし？

私は常にPackage.htmlを使用してきました。しかし、私はそれが正しい選択かどうか疑問に思っています。

java javadoc

— TheLQ
ソース

package-info.java[package]アノテーションを含めることができます-すべてのAPIドキュメントである必要はありません。

— トム・ホーティン-タックライン

私はpackage-info.javaをクラスの乱用とは見なしません。これはJavaソースファイル（「.java」ファイル拡張子があります）ですが、クラス宣言が含まれていないため、クラスファイルではありません。そして、実際には、「package-info」は正当なクラス名ではないため、クラス宣言を含めることはできません。

— スクラビー

package.htmlの代わりにpackage-info.javaを使用するもう1つの理由は、.javaがドキュメントの特定の出力形式を示唆していないことです。たとえば、javadocをLaTeXまたはPDFファイルとして出力できます。javadocコンパイラの実装によっては、.htmlの場合に問題が発生する可能性があります。

— honeyp0t

実際には@Scrubbie-正しいはずですが、そこにpackage-privateクラスを指定できると思います。:-(私が使用して、しかし、あなたの感情に同意package-info.javaのJavadocと注釈のクラスの乱用ではありません。

— mjaggard

@JonasNは、stackoverflow.com / a / 14708381/751579を参照してください（3年前にこの問題が発生したことはわかっていますが、おそらく誰か他の人が今すぐヒントを必要としています）

— davidbak

269

package-info.java：「このファイルはJDK 5.0で新しく追加され、package.htmlよりも優先されます。」— javadoc-Java APIドキュメントジェネレーター

補遺：大きな違いはパッケージの注釈のようです。7.4パッケージ宣言では、理論的根拠がもう少しあります。

補遺：アノテーション機能についても、こことここで説明されています。

補遺：何をpackage-info.java参照してください。。

— ゴミ神
ソース

それが好まれる理由は何ですか？

— TheLQ

@TheLQ：コンパイラーにはさらに多くの情報が必要なので、パッケージの注釈を推測しています。以上。

— trashgod

パッケージアノテーションは私にとって新しいものであり、package-info.javaはスコープが広いため、その理由として適切です。

— スタッカー

回答をもう少し編集します。「パッケージアノテーション」について説明します。これは、パッケージ内のすべてのクラス、またはパッケージ全体に適用されるアノテーションです。tech.puredanger.comリンクは、なぜ私が気にする必要があるのかを本当に説明する唯一のリンクでした。そうは言っても、それは良い、役に立つリンクです。

— Roboprog

package-info.javaを使用すると、{@ link}およびその他のドックレットを使用できます。java.langクラスをリンクすると、javadocが生成されるときに、使用しているjdkに一致するクラスのオンラインjavadocを指す{@link}が自動的に取得されます。ideは、リファクタリングを行うときに間違ったリンクを見つけるのにも役立ちます。

— Luigi R. Viggiano 2013年