盡管用于javadoc工具的JDK工具和實用程序頁面通過實現(xiàn)和繼承方法來描述Javadoc方法注釋重用的規(guī)則，但是當實際上不需要使用{@inheritDoc}時，很容易不必要地顯式描述注釋繼承，因為會使用相同的注釋隱式繼承。 Java 8 javadoc工具頁面在“ 方法公共繼承 ”部分描述了繼承方法Javadoc注釋的規(guī)則，而Java 7 javadoc工具頁面在“ 方法注釋的自動復制 ”部分類似地描述了這些規(guī)則。 這篇文章使用簡單的代碼示例來說明Javadoc方法注釋繼承的一些關(guān)鍵規(guī)則。

以下接口和類是人為設(shè)計的示例，這些示例將在本文中用于說明對方法的Javadoc注釋的繼承。 一些繼承/實現(xiàn)的方法包括它們自己的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.*/@Overridepublic void eat(final Animal otherAnimal){}/*** {@inheritDoc}* @param plantToBeEaten Plant that this dog will eat.*/@Overridepublic void eat(final Plant plantToBeEaten){}/*** {@inheritDoc}* Bark.*/public void verballyCommunicate(){out.println("Woof!");}/*** {@inheritDoc}* @param numberPuppies Number of puppies being born.*/@Overridepublic void giveBirth(final int numberPuppies){}/*** Provide the color of the dog's hair.** @return Color of the dog's fur.*/@Overridepublic 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}*/@Overridepublic void eat(final Animal otherAnimal){}@Overridepublic void verballyCommunicate(){out.println("Meow");}@Overridepublic void giveBirth(int numberKittens){}@Overridepublic 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.*/@Overridepublic void eat(final Plant plant){}/****/@Overridepublic void verballyCommunicate(){out.println("Neigh");}/*** @param numberColts Number of colts to be born to horse.*/@Overridepublic void giveBirth(int numberColts){}@Overridepublic Color getHairColor(){return hairColor;} }

下一個屏幕快照顯示了包的內(nèi)容，其中包括上面顯示了代碼清單的接口和類（并非包中的所有類和接口都顯示了其代碼清單）。

從方法的Javadoc角度來看，這里最感興趣的三個類是Dog ， Cat和Horse類，因為它們實現(xiàn)了多個接口并擴展了MamalWithHair ，后者擴展了Mammal ，后者擴展了Animal 。

下一個屏幕快照是在Web瀏覽器中呈現(xiàn)的Animal類的Javadoc的快照。

Animal類不會從超類繼承任何方法，也不會從接口實現(xiàn)任何方法，對于本博客文章的主題而言，這不是很有趣。 但是，這里顯示的其他類擴展了該類，因此很有趣的是看到其方法注釋如何影響繼承類的方法說明。

接下來的兩個屏幕快照是在Web瀏覽器中呈現(xiàn)的Mammal和MammalWithHair類的Javadoc的快照。 關(guān)于Mammal任何意義，沒有Javadoc注釋，但是對于MammalWithHair引入的新方法，只有一個方法注釋。

接下來的三個屏幕快照是Web瀏覽器中用于Herbivorous ， Carnivorous和Omnivorous接口的Javadoc文檔子集。 這些接口提供了將由實現(xiàn)這些方法的類繼承的方法的文檔。

使用為父類和接口顯示的生成的Javadoc方法文檔，現(xiàn)在可以查看為擴展這些類并實現(xiàn)這些接口的類的方法生成的文檔。

前面顯示的Dog類中的方法通常將{@inheritDoc}與其他文本結(jié)合使用。 從擴展類和已實現(xiàn)的接口繼承Javadoc注釋方法的結(jié)果與Dog注釋中提供的附加測試相結(jié)合，顯示在下一個屏幕快照中。

屏幕快照的最后一組展示了Dog類的文檔將其“父母”的文檔與自己的特定文檔混合在一起。 這不足為奇。 Dog類的方法通常從父類（基類和接口）顯式繼承Javadoc文檔，但是Cat類除其eat方法（僅使用{@inheritDoc} ）外，幾乎沒有對其方法的Javadoc注釋。 下一個屏幕快照顯示了從此類生成的Web瀏覽器輸出。

Cat中沒有應用Javadoc注釋的方法會在生成的Web瀏覽器文檔中顯示，這些文檔的文檔是從其基類或接口繼承的，而這些方法的文檔包括短語“從類復制說明：”或“從接口復制說明： “ 作為適當?shù)摹?明確包含文檔標記{@inheritDoc}的一個Cat方法確實復制了父方法的文檔，但不包含“從...復制說明”消息。

Horse類的方法通常根本沒有記錄在文檔中，因此它們生成的文檔包括消息“從...復制說明”。 Horse類的eat()和giveBirth()方法會覆蓋@param部分，因此生成的Web瀏覽器文檔中的這兩個方法的參數(shù)文檔（在下一組屏幕快照中顯示）特定于Horse 。

從上面的代碼清單和該代碼生成的文檔的屏幕快照，可以通過擴展和實現(xiàn)類來觀察方法Javadoc注釋的繼承。 這些觀察結(jié)果也在javadoc工具文檔中進行了描述：

• Javadoc注釋從父類的方法和已實現(xiàn)的接口方法繼承，或者在未指定文本時隱式繼承（根本沒有Javadoc或空Javadoc /** */ ）。
  • javadoc文檔 ：“ javadoc命令允許在類和接口中繼承方法注釋，以填充缺少的文本或顯式繼承方法注釋。”
• 使用{@inheritDoc}明確指出應繼承注釋。
  • Javadoc文檔 ：“插入{@inheritDoc}的方法中的主要描述或內(nèi)嵌代碼@return ， @param ，或@throws標記注釋。
• 通過在方法注釋內(nèi)不同位置使用{@inheritDoc}標簽，可以組合使用方法文檔的隱式和顯式繼承。

鑒于上述觀察結(jié)果，并提供了廣告宣傳的“ 方法注釋算法 ”，從Javadoc生成HTML角度來看，編寫Javadoc的一個好的經(jīng)驗法則是在盡可能高的級別上定義一般注釋，并允許自動繼承擴展類和已實現(xiàn)接口的方法的Javadoc文檔將出現(xiàn)，僅添加或覆蓋方法的Javadoc文本的某些部分，這些部分對于澄清或增強對低級方法的描述是必需的。 這比在繼承或?qū)崿F(xiàn)層次結(jié)構(gòu)中的所有方法上復制并粘貼相同的注釋，然后再將它們?nèi)扛略谝黄鸶谩?

這篇文章重點介紹了生成的Javadoc方法文檔的Web瀏覽器演示。 幸運的是，最常用的Java IDE（ NetBeans [ CTRL + hover ]， IntelliJ IDEA [ CTRL + Q / 設(shè)置 ]， Eclipse [ F2 / hover / Javadoc View ]和JDeveloper [ CTRL-D ]）支持Javadoc的演示，遵循方法文檔繼承的相同規(guī)則。 這意味著Java開發(fā)人員通常可以編寫較少的文檔，幾乎可以完全避免在繼承和實現(xiàn)層次結(jié)構(gòu)中重復文檔。

翻譯自: https://www.javacodegeeks.com/2016/11/inheriting-javadoc-method-comments.html

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎勵來咯，堅持創(chuàng)作打卡瓜分現(xiàn)金大獎

總結(jié)

以上是生活随笔為你收集整理的继承Javadoc方法注释的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。