Java

Javadocメソッドのコメントを継承する



Inherit Javadoc Method Comments



使用されていますが javadocツール の JDKツールとユーティリティ このページでは、実装メソッドと継承メソッドによるJavadocメソッドアノテーションの再利用のルールについて説明していますが、実際に使用する必要がない場合は{@inheritDoc}同じアノテーションの暗黙的な継承が行われるため、アノテーションの継承を不必要に明示的に説明するのは簡単です。中古。 Java 8javadocツールページ 'で メソッドのパブリック継承 'パートでは、継承されたメソッドに対するJavadocコメントのルールについて説明します。 Java 7javadocツールページ 'で メソッドコメントの自動コピー このセクションでは、これらのルールについても同様に説明します。 この記事では、簡単なコード例を使用して、Javadocメソッドのアノテーション継承のいくつかの重要なルールを説明します。

次のインターフェースとクラスは、メソッドのJavadocコメントの継承を説明するためにこの記事で使用される人工的に設計された例です。 一部の継承/実装されたメソッドには、親/インターフェイスメソッドのアノテーションを完全にまたは部分的にオーバーライドする独自のJavadocコメントが含まれていますが、他のメソッドは、親/インターフェイスメソッドを再利用するための単なるドキュメントです。



草食性のインターフェース

package dustin.examples.inheritance /** * Marks animals that eat plants. */ public interface Herbivorous { /** * Eat the provided plant. * * @param plantToBeEaten Plant that will be eaten. */ void eat(Plant plantToBeEaten) }

肉食的なインターフェース



package dustin.examples.inheritance /** * Marks an Animal that eats other animals. */ public interface Carnivorous { /** * Eat the provided animal. * * @param animalBeingEaten Animal that will be eaten. */ void eat(Animal animalBeingEaten) }

雑食性のインターフェース

package dustin.examples.inheritance /** * Eats plants and animals. */ public interface Omnivorous extends Carnivorous, Herbivorous { }

胎生インターフェース

package dustin.examples.inheritance /** * Mammals that give birth to young that develop within * the mother's body. */ public interface Viviparous { /** * Give birth to indicated number of offspring. * * @param numberOfOffspring Number of offspring being born. */ void giveBirth(int numberOfOffspring) }

動物



package dustin.examples.inheritance /** * Animal. */ public abstract class Animal { /** * Breathe. */ public void breathe() { } /** * Communicate verbally. */ public abstract void verballyCommunicate() }

哺乳類

package dustin.examples.inheritance /** * Mammal. */ public abstract class Mammal extends Animal { }

哺乳類

package dustin.examples.inheritance import java.awt.* /** * Mammal with hair (most mammals other than dolphins and whales). */ public abstract class MammalWithHair extends Mammal { /** Provide mammal's hair color. */ public abstract Color getHairColor() }

犬

package dustin.examples.inheritance import java.awt.Color import static java.lang.System.out /** * Canine and man's best friend. */ public class Dog extends MammalWithHair implements Omnivorous, Viviparous { private final Color hairColor = null /** * {@inheritDoc} * @param otherAnimal Tasty treat. */ @Override public void eat(final Animal otherAnimal) { } /** * {@inheritDoc} * @param plantToBeEaten Plant that this dog will eat. */ @Override public void eat(final Plant plantToBeEaten) { } /** * {@inheritDoc} * Bark. */ public void verballyCommunicate() { out.println('Woof!') } /** * {@inheritDoc} * @param numberPuppies Number of puppies being born. */ @Override public void giveBirth(final int numberPuppies) { } /** * Provide the color of the dog's hair. * * @return Color of the dog's fur. */ @Override public Color getHairColor() { return hairColor } }

猫

package dustin.examples.inheritance import java.awt.Color import static java.lang.System.out /** * Feline. */ public class Cat extends MammalWithHair implements Carnivorous, Viviparous { private final Color hairColor = null /** * {@inheritDoc} */ @Override public void eat(final Animal otherAnimal) { } @Override public void verballyCommunicate() { out.println('Meow') } @Override public void giveBirth(int numberKittens) { } @Override public Color getHairColor() { return hairColor } }

うま

package dustin.examples.inheritance import java.awt.Color import static java.lang.System.out /** * Equine. */ public class Horse extends MammalWithHair implements Herbivorous, Viviparous { private final Color hairColor = null /** * @param plant Plant to be eaten by this horse. */ @Override public void eat(final Plant plant) { } /** * */ @Override public void verballyCommunicate() { out.println('Neigh') } /** * @param numberColts Number of colts to be born to horse. */ @Override public void giveBirth(int numberColts) { } @Override public Color getHairColor() { return hairColor } }

次のスクリーンショットは、コードリストが上に示されているインターフェイスとクラスを含むパッケージの内容を示しています（パッケージ内のすべてのクラスとインターフェイスがコードリストを示しているわけではありません）。

20161116- javadoc

メソッドのJavadocの観点から、ここで最も重要な3つのクラスはDogです。 、Cat with Horseクラス、複数のインターフェースを実装し、拡張するためMamalWithHair 、後者は拡張しますMammal 、後者は拡張しますAnimal 。

次のスクリーンショットは、Webブラウザに表示されますAnimalクラスのJavadocのスナップショット。

20161119-animaljavadoc-1

Animalクラスはスーパークラスからメソッドを継承せず、インターフェイスからメソッドを実装しません。これは、このブログ投稿の主題にとってあまり興味深いものではありません。 ただし、ここに示されている他のクラスはこのクラスを拡張しているため、そのメソッドアノテーションが継承されたクラスのメソッド記述にどのように影響するかを確認するのは興味深いことです。

次の2つのスクリーンショットは、WebブラウザでレンダリングされますMammal with MammalWithHairクラスのJavadocのスナップショット。 on Mammalどのような意味でも、Javadocコメントはありませんが、for MammalWithHair導入された新しいメソッドにはメソッドコメントが1つしかありません。

20161119- javadoc

20161119-

次の3つのスクリーンショットは、Webブラウザーで使用されますHerbivorous 、Carnivorous with OmnivorousインターフェースのJavadocドキュメントのサブセット。 これらのインターフェースは、これらのメソッドを実装するクラスによって継承されるメソッドのドキュメントを提供します。

20161119- javadoc

20161119- javadoc

20161119- javadoc

親クラスおよびインターフェース用に生成されたJavadocメソッドのドキュメントを使用して、これらのクラスを拡張し、これらのインターフェースを実装するクラスのメソッド用に生成されたドキュメントを表示できるようになりました。

前に示したDogクラスのメソッドは通常{@inheritDoc}他のテキストと組み合わせて使用​​されます。 拡張クラスおよび実装されたインターフェイスからJavadocアノテーションメソッドを継承した結果は、Dogと同じです。コメントで提供されている追加のテストを組み合わせて、次のスクリーンショットに示します。

20161119-dogjavadoc

20161119- javadocmethoddetailtop

20161119-dogjavadocmethoddetailbottom

スクリーンショットの最後のセットは次のことを示していますDogクラスのドキュメントは、その「親」のドキュメントとそれ自体の特定のドキュメントを混合しています。 これは驚くべきことではありません。 Dogクラスのメソッドは通常、親クラス（基本クラスとインターフェイス）から明示的にJavadocドキュメントを継承しますが、Catそれ以外のクラスeatメソッド（使用のみ{@inheritDoc} ）さらに、そのメソッドに関するJavadocコメントはほとんどありません。 次のスクリーンショットは、このクラスから生成されたWebブラウザーの出力を示しています。

20161119-catjavadoc

20161119- javadocmethoddetail

Cat Javadocコメントが適用されないメソッドは、生成されたWebブラウザーのドキュメントに表示されます。これらのドキュメントのドキュメントは、その基本クラスまたはインターフェイスから継承され、これらのメソッドのドキュメントには、「クラスからの説明のコピー：」または「インターフェイスからの説明のコピー」というフレーズが含まれます。 ドキュメントマークアップを明示的に含める{@inheritDoc} 1つCatメソッドは親メソッドのドキュメントをコピーしますが、「copy descriptionfrom」メッセージは含まれません。

Horse通常、クラスのメソッドはまったく文書化されていないため、生成される文書には「copydescriptionfrom」というメッセージが含まれています。 Horseカテゴリeat() with giveBirth()メソッドはオーバーライドします@paramパートなので、生成されたWebブラウザドキュメント（次のスクリーンショットのセットに表示）にあるこれら2つのメソッドのパラメータドキュメントHorseに固有です。

20161119-

20161119-

20161119-

上記のコードリストとこのコードによって生成されたドキュメントのスクリーンショットから、クラスを拡張および実装することにより、メソッドJavadocコメントの継承を観察できます。 これらの観察も javadocツールのドキュメント 説明：

  • Javadocコメントは、親クラスのメソッドと実装されたインターフェイスメソッドから継承されるか、テキストが指定されていない場合は暗黙的に継承されます（Javadocがないか空のJavadocがまったくない/** */）。
      javadocドキュメント ：“ javadocこのコマンドを使用すると、メソッドコメントをクラスおよびインターフェイスに継承して、欠落しているテキストを埋めたり、メソッドコメントを明示的に継承したりできます。 '
  • use {@inheritDoc}コメントを継承する必要があることを明確にします。
      Javadocドキュメント ： '挿入{@inheritDoc}メソッドの主な説明または埋め込みコード@return 、@param 、または@throwsコメントをマークします。
  • メソッドコメントのさまざまな場所で使用することにより{@inheritDoc}タグは、メソッドドキュメントの暗黙的および明示的な継承と組み合わせて使用​​できます。

上記の観察を考慮して、広告を提供しました ' メソッドアノテーションアルゴリズム 'HTMLを生成するJavadocの観点から、Javadocを作成するための経験則は、一般的なコメントを可能な限り高いレベルで定義することです。拡張クラスと実装されたインターフェイスのメソッドの自動継承を許可するJavadocドキュメントが表示され、追加またはカバーするだけです。低レベルメソッドの説明を明確化または強化するために必要な、メソッドのJavadocテキストの一部。 これは、継承または実装階層内のすべてのメソッドに同じコメントをコピーして貼り付けてから、それらをすべて一緒に更新するよりも優れています。

この記事では、生成されたJavadocメソッドのドキュメントのWebブラウザのデモンストレーションに焦点を当てています。 幸い、最も一般的に使用されているJava IDE（ NetBeans [ Ctrlキーを押しながらホバーします ]、 IntelliJ IDEA [ CTRL + Q / セットアップ ]、 Eclipse [ F2 /ホバー/ Javadocビュー ]と JDeveloper [ CTRL-D ]）Javadocのプレゼンテーションをサポートし、メソッドドキュメントの継承と同じルールに従います。 つまり、Java開発者は通常、より少ないドキュメントを作成でき、継承および実装階層でのドキュメントの重複をほぼ完全に回避できます。

翻訳元： https://www.javacodegeeks.com/2016/11/inheriting-javadoc-method-comments.html