欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

继承Javadoc方法注释

程序员文章站 2022-07-13 17:13:21
...

尽管用于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方法注释

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

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

继承Javadoc方法注释

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

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

继承Javadoc方法注释

继承Javadoc方法注释

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

继承Javadoc方法注释

继承Javadoc方法注释

继承Javadoc方法注释

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

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

继承Javadoc方法注释

继承Javadoc方法注释

继承Javadoc方法注释

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

继承Javadoc方法注释

继承Javadoc方法注释

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

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

继承Javadoc方法注释

继承Javadoc方法注释

继承Javadoc方法注释

从上面的代码清单和该代码生成的文档的屏幕快照,可以通过扩展和实现类来观察方法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

上一篇: 抓包工具

下一篇: switch