继承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.
    */
   @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类除其eat方法（仅使用{@inheritDoc} ）外，几乎没有对其方法的Javadoc注释。 下一个屏幕快照显示了从此类生成的Web浏览器输出。

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

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

从上面的代码清单和该代码生成的文档的屏幕快照，可以通过扩展和实现类来观察方法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开发人员通常可以编写较少的文档，几乎可以完全避免在继承和实现层次结构中重复文档。

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