建筑工程信息网站,建设网站公司域名,不愁销路的小型加工厂项目年入百万,如何做seo搜索引擎优化尽管用于javadoc工具的JDK工具和实用程序页面通过实现和继承方法来描述Javadoc方法注释重用的规则#xff0c;但是当实际上不需要使用{inheritDoc}时#xff0c;很容易不必要地显式描述注释继承#xff0c;因为会使用相同的注释隐式继承。 Java 8 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 mothers 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 mammals hair color. */public abstract Color getHairColor();
} 狗类 package dustin.examples.inheritance;import java.awt.Color;import static java.lang.System.out;/*** Canine and mans 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 dogs hair.** return Color of the dogs 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;}
} 下一个屏幕快照显示了包的内容其中包括上面显示了代码清单的接口和类并非包中的所有类和接口都显示了其代码清单。 从方法的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
