尽管 javadoc 工具的JDK Tools and Utilities页面通过实现和继承方法描述了 Javadoc 方法注释重用的规则，但是很容易不必要地显式地描述注释继承与 {@inheritDoc} 当它不是真正需要的时候，因为相同的注释将被隐式继承。 Java 8 javadoc工具页在“Method Common Inheritance”一节和Java 7 javadoc工具页中描述了继承方法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
{
}
MammalWithHair 类
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;
}
}
下一个屏幕快照显示包的内容，其中包括上面显示其代码清单的接口和类（并非包中的所有类和接口都显示了它们的代码清单）。
从方法的 Javadoc 角度来看，这里最感兴趣的三个类是类 Dog、Cat 和 Horse，因为它们实现了多个接口并扩展了 MamalWithHair，它扩展了 Mammal，它扩展了 Animal。
下一个屏幕快照是在 Web 浏览器中呈现的 Animal 类的 Javadoc。
Animal 类不从超类继承任何方法，也不从接口实现任何方法，对于这篇博文的主题来说不是很有趣。然而，这里显示的其他类扩展了这个类，所以看看它的方法注释如何影响继承类的方法描述是很有趣的。
接下来的两个屏幕快照是在 Web 浏览器中呈现的 Mammal 和 MammalWithHair 类的 Javadoc。 Mammal 上没有关于任何意义的 Javadoc 注释，但有一个方法注释是针对 MammalWithHair 引入的新方法。
接下来的三个屏幕快照是 Web 浏览器中接口 Herbivorous、Carnivorous 和 Omnivorous 的 Javadoc 文档的子集。这些接口为将由实现这些方法的类继承的方法提供文档。
为父类生成的 Javadoc 方法文档和显示的接口，现在是时候查看为扩展这些类和实现这些接口的类的方法生成的文档了。
前面显示的 Dog 类中的方法通常将 {@inheritDoc} 与其他文本结合使用。从扩展类和实现的接口继承方法 Javadoc 注释，结合 Dog 的注释中提供的附加测试的结果显示在下一个屏幕快照中。
最后一组屏幕截图表明，Dog 类的文档将其“父级”的文档与其自身的特定文档混合在一起。这并不奇怪。 Dog 类的方法通常显式地从父类（基类和接口）继承 Javadoc 文档，但是 Cat 类的方法大多没有 Javadoc 注释，除了 eat 方法，它只使用 {@inheritDoc}。此类生成的 Web 浏览器输出显示在下一个屏幕快照中。
Cat 中没有应用 Javadoc 注释的方法显示在生成的 Web 浏览器文档中，文档继承自它们的基类或接口，这些方法的文档包括短语“从类复制的描述：”或“从界面复制的说明：”视情况而定。一个明确包含文档标记 Cat 的 {@inheritDoc} 方法会复制父方法的文档，但不包含“Description copied from”消息。
Horse 类的方法通常根本没有文档，因此它们生成的文档包含消息“Description copied from...”。 eat() 类的 giveBirth() 和 Horse 方法覆盖了 @param 部分，因此这两个方法的参数文档在生成的 Web 浏览器文档中（显示在下一组屏幕快照中）特定于 Horse。
从上面的代码清单和从该代码生成的文档的屏幕快照，可以对通过扩展和实现类继承方法的 Javadoc 注释进行一些观察。 javadoc 工具文档 中也描述了这些观察结果：
- Javadoc 注释是从父类的方法和实现的接口方法继承的，或者在没有指定文本时隐式继承（根本没有 Javadoc 或空 Javadoc
/** */）。- javadoc 文档：“
javadoc命令允许类和接口中的方法注释继承来填充缺失的文本或显式继承方法注释。”
- javadoc 文档：“
- 使用
{@inheritDoc}明确说明注释应该被继承。- javadoc 文档：“在方法主要描述或
{@inheritDoc}、@return中插入@param内联标记，或@throws标签注释。相应继承的主要描述或标签评论复制到该位置。”
- javadoc 文档：“在方法主要描述或
- 通过在方法注释的不同位置使用
{@inheritDoc}标签，可以组合实现方法文档的隐式和显式继承。
鉴于上述观察和广告中的“方法注释算法”，从 Javadoc 生成的 HTML 的角度来看，编写 Javadoc 的一个好的经验法则是将一般注释定义在与可能并允许自动继承扩展类和实现的接口的方法的 Javadoc 文档，仅添加或覆盖方法的 Javadoc 文本的一部分，这些文本对于阐明或增强对较低级别方法的描述是必需的。这比在继承或实现层次结构中的所有方法上复制和粘贴相同的注释，然后需要让它们一起更新要好。
这篇文章的重点是生成的 Javadoc 方法文档的 Web 浏览器演示。幸运的是，最常用的 Java IDE（NetBeans [CTRL+hover]、IntelliJ IDEA [CTRL+Q / Settings]、Eclipse [F2 / hover / Javadoc View] 和 JDeveloper [CTRL- D]) 支持通常遵循相同的方法文档继承规则的 Javadoc 表示。这意味着 Java 开发人员通常可以编写更少的文档，并且几乎可以完全避免在继承和实现层次结构中重复编写文档。
标签2： Java教程地址：https://www.cundage.com/article/jcg-inheriting-javadoc-method-comments.html
相关阅读
