继承Javadoc方法注释

尽管用于javadoc工具的JDK工具和实用程序页面通过实现和继承方法来描述Javadoc方法注释重用的规则，但是当实际上不需要使用{@inheritDoc}时，很容易不必要地显式描述注释继承，因为会使用相同的注释隐式继承。 Java 8 javadoc工具页面在“ 方法公共继承 ”部分描述了继承方法Javadoc注释的规则，而Java 7 javadoc工具页面在“ 方法注释的自动复制 ”部分类似地描述了这些规则。这篇文章使用简单的代码示例来说明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.*/@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;}
}

下一个屏幕快照显示了包的内容，其中包括上面显示了代码清单的接口和类（并非包中的所有类和接口都显示了其代码清单）。

20161116-继承包javadoc

从方法的Javadoc角度来看，这里最感兴趣的三个类是Dog ， Cat和Horse类，因为它们实现了多个接口并扩展了MamalWithHair ，后者扩展了Mammal ，后者扩展了Animal 。

下一个屏幕快照是在Web浏览器中呈现的Animal类的Javadoc的快照。

20161119-animaljavadoc-1

Animal类不会从超类继承任何方法，也不会从接口实现任何方法，对于本博客文章的主题而言，这不是很有趣。但是，这里显示的其他类扩展了该类，因此很有趣的是看到其方法注释如何影响继承类的方法说明。

接下来的两个屏幕快照是在Web浏览器中呈现的Mammal和MammalWithHair类的Javadoc的快照。关于Mammal任何意义，没有Javadoc注释，但是对于MammalWithHair引入的新方法，只有一个方法注释。

20161119-哺乳动物javadoc

20161119-哺乳动物与毛发方法摘要

接下来的三个屏幕快照是Web浏览器中用于Herbivorous ， Carnivorous和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}的一个Cat方法确实复制了父方法的文档，但不包含“从...复制说明”消息。

Horse类的方法通常根本没有记录在文档中，因此它们生成的文档包括消息“从...复制说明”。 Horse类的eat()和giveBirth()方法会覆盖@param部分，因此生成的Web浏览器文档中的这两个方法的参数文档（在下一组屏幕快照中显示）特定于Horse 。

20161119-马法摘要

20161119-马法详细

20161119-马法详细底部

从上面的代码清单和该代码生成的文档的屏幕快照，可以通过扩展和实现类来观察方法Javadoc注释的继承。这些观察结果也在javadoc工具文档中进行了描述：

Javadoc注释从父类的方法和已实现的接口方法继承，或者在未指定文本时隐式继承（根本没有Javadoc或空Javadoc /** */ ）。
- javadoc文档：“ javadoc命令允许在类和接口中继承方法注释，以填充缺少的文本或显式继承方法注释。”
使用{@inheritDoc}明确指出应继承注释。
- Javadoc文档：“插入{@inheritDoc}的方法中的主要描述或内嵌代码@return ， @param ，或@throws标记注释。
通过在方法注释内不同位置使用{@inheritDoc}标签，可以组合使用方法文档的隐式和显式继承。

鉴于上述观察结果，并提供了广告宣传的“ 方法注释算法 ”，从Javadoc生成HTML角度来看，编写Javadoc的一个好的经验法则是在尽可能高的级别上定义一般注释，并允许自动继承扩展类和已实现接口的方法的Javadoc文档将出现，仅添加或覆盖方法的Javadoc文本的某些部分，这些部分对于澄清或增强对低级方法的描述是必需的。这比在继承或实现层次结构中的所有方法上复制并粘贴相同的注释，然后再将它们全部更新在一起更好。

这篇文章重点介绍了生成的Javadoc方法文档的Web浏览器演示。幸运的是，最常用的Java IDE（ NetBeans [ CTRL + hover ]， IntelliJ IDEA [ CTRL + Q / 设置 ]， Eclipse [ F2 / hover / Javadoc View ]和JDeveloper [ CTRL-D ]）支持Javadoc的演示，遵循方法文档继承的相同规则。这意味着Java开发人员通常可以编写较少的文档，几乎可以完全避免在继承和实现层次结构中重复文档。