继承Javadoc方法注释

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

以下接口和类是人为设计的示例&＃xff0c;这些示例将在本文中用于说明对方法的Javadoc注释的继承。 一些继承/实现的方法包括它们自己的Javadoc注释&＃xff0c;这些注释会完全或部分覆盖父/接口的方法注释&＃xff0c;而其他方法只是重用父/接口的方法的文档。

草食界面

package dustin.examples.inheritance;/*** Marks animals that eat plants.*/
public interface Herbivorous
{/*** Eat the provided plant.** &＃64;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.** &＃64;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&＃39;s body.*/
public interface Viviparous
{/*** Give birth to indicated number of offspring.** &＃64;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&＃39;s hair color. */public abstract Color getHairColor();
}

狗类

package dustin.examples.inheritance;import java.awt.Color;import static java.lang.System.out;/*** Canine and man&＃39;s best friend.*/
public class Dog extends MammalWithHair implements Omnivorous, Viviparous
{private final Color hairColor &＃61; null;/*** {&＃64;inheritDoc}* &＃64;param otherAnimal Tasty treat.*/&＃64;Overridepublic void eat(final Animal otherAnimal){}/*** {&＃64;inheritDoc}* &＃64;param plantToBeEaten Plant that this dog will eat.*/&＃64;Overridepublic void eat(final Plant plantToBeEaten){}/*** {&＃64;inheritDoc}* Bark.*/public void verballyCommunicate(){out.println("Woof!");}/*** {&＃64;inheritDoc}* &＃64;param numberPuppies Number of puppies being born.*/&＃64;Overridepublic void giveBirth(final int numberPuppies){}/*** Provide the color of the dog&＃39;s hair.** &＃64;return Color of the dog&＃39;s fur.*/&＃64;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 &＃61; null;/*** {&＃64;inheritDoc}*/&＃64;Overridepublic void eat(final Animal otherAnimal){}&＃64;Overridepublic void verballyCommunicate(){out.println("Meow");}&＃64;Overridepublic void giveBirth(int numberKittens){}&＃64;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 &＃61; null;/*** &＃64;param plant Plant to be eaten by this horse.*/&＃64;Overridepublic void eat(final Plant plant){}/****/&＃64;Overridepublic void verballyCommunicate(){out.println("Neigh");}/*** &＃64;param numberColts Number of colts to be born to horse.*/&＃64;Overridepublic void giveBirth(int numberColts){}&＃64;Overridepublic Color getHairColor(){return hairColor;}
}

下一个屏幕快照显示了包的内容&＃xff0c;其中包括上面显示了代码清单的接口和类&＃xff08;并非包中的所有类和接口都显示了其代码清单&＃xff09;。

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

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

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

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

接下来的三个屏幕快照是Web浏览器中用于Herbivorous &＃xff0c; Carnivorous和Omnivorous接口的Javadoc文档子集。 这些接口提供了将由实现这些方法的类继承的方法的文档。

使用为父类和接口显示的生成的Javadoc方法文档&＃xff0c;现在可以查看为扩展这些类并实现这些接口的类的方法生成的文档。

前面显示的Dog类中的方法通常将{&＃64;inheritDoc}与其他文本结合使用。 从扩展类和已实现的接口继承Javadoc注释方法的结果与Dog注释中提供的附加测试相结合&＃xff0c;显示在下一个屏幕快照中。

屏幕快照的最后一组展示了Dog类的文档将其“父母”的文档与自己的特定文档混合在一起。 这不足为奇。 Dog类的方法通常从父类&＃xff08;基类和接口&＃xff09;显式继承Javadoc文档&＃xff0c;但是Cat类除其eat方法&＃xff08;仅使用{&＃64;inheritDoc} &＃xff09;外&＃xff0c;几乎没有对其方法的Javadoc注释。 下一个屏幕快照显示了从此类生成的Web浏览器输出。

Cat中没有应用Javadoc注释的方法会在生成的Web浏览器文档中显示&＃xff0c;这些文档的文档是从其基类或接口继承的&＃xff0c;而这些方法的文档包括短语“从类复制说明&＃xff1a;”或“从接口复制说明&＃xff1a; “ 作为适当的。 明确包含文档标记{&＃64;inheritDoc}的一个Cat方法确实复制了父方法的文档&＃xff0c;但不包含“从...复制说明”消息。

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

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

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

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

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

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