继承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.*/@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 dog's hair.** @return Color of the dog's 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
命令允许在类和接口中继承方法注释,以填充缺少的文本或显式继承方法注释。”
- 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 / 设置 ], Eclipse [ F2 / hover / Javadoc View ]和JDeveloper [ CTRL-D ])支持Javadoc的演示,遵循方法文档继承的相同规则。 这意味着Java开发人员通常可以编写较少的文档,几乎可以完全避免在继承和实现层次结构中重复文档。
翻译自: https://www.javacodegeeks.com/2016/11/inheriting-javadoc-method-comments.html
继承Javadoc方法注释相关推荐
- 接口方法javadoc注释_继承Javadoc方法注释
接口方法javadoc注释 尽管用于javadoc工具的JDK工具和实用程序页面通过实现和继承方法来描述Javadoc方法注释重用的规则,但是当实际上不需要使用{@inheritDoc}时,很容易不必 ...
- idea java doc 模板_IntelliJ IDEA 符合 JavaDOC 的注释模板设置方法
类注释模板: /*** @version 0.1.0** @author your name or email** @since 0.1.0** @create ${YEAR}-${MONTH}-${ ...
- idea设置Java类注释和方法注释模板(javadoc规范)
1.类注释模板设置 File–>settings–>Editor–>File and Code Templates–>Files 添加模板: 简版: /** * [一句话描述该 ...
- IntelliJ IDEA 2022 类和方法注释模板设置
一.概述 IDEA自带的注释模板一般都很简单,然而我们在写代码的时候喜欢把类注释和文档注释写在代码里,既方便自己看所有的参数,也便于以后维护代码的时候看到编码作者.下面是我的代码注释,我们就按照这种格 ...
- IntelliJ IDEA设置类注释和方法注释
默认情况下,idea生成javadoc注释时,类上面使用时内容为空,方法上使用时会生成参数.返回值和抛出的异常,如果想显示@author.@date等信息时,则需要自己配置了. 一.类注释 方法一:创 ...
- Eclipse配置代码注释模板 Eclipse代码注释模板 Eclipse设置方法注释模板
Eclipse配置代码注释模板 Eclipse代码注释模板 Eclipse设置方法注释模板 一.前言 1.在日常的团队开发中,都会有相应的的代码开发规范模板:在不同的IDE中配置方式又是不一样的,本文 ...
- 方法 注释_注释模板导入操作方法
一.添加新建类的注释模板 路径:File -> Settings -> File and Code Templates 添加如下信息 /** * //TODO 添加类/接口功能描述 * * ...
- 4.9.3 方法注释
每一个方法注释必须放在所描述的方法之前.除了通用标记之外,还可以使用下面的标记: @param variable description 这个标记将对当前方法的"param"(参数 ...
- zend studio自动添加文件注释和方法注释
zend studio自动添加文件注释和方法注释 进入首选项=>PHP=>Editor=>Template=>New Name\Description\Pattern里面分别填 ...
最新文章
- ssm jsp跳转jsp_去掉Shiro默认login.jsp跳转
- 哈佛成功金句25则(看一遍,都会很有收获!)
- python 时间减去一天_Python是个什么鬼?为什么985学生都在学它?!
- 从数据类型 nvarchar 转换为 numeric 时出错_Python数据分析类库系列Numpy之ndarray的数据类型...
- 读取STM32单片机-ID操作
- python pexpect timeout_Python 的 pexpect 模块的问题
- Oracle从零开始1——SQLplus
- 一个相当好的状态机(DFA, 确定有限状态机)的编码实现,相当简洁漂亮
- es6 实例:使用Proxy实现观察者模式
- 想了解表格问答,我们先看看TA的前世
- 区块链架构1.0、2.0与3.0梳理
- 改进的树状长短期记忆网络(Tree-LSTM)语义表示
- 3.2.CPU中的实模式
- NoSQL和MemeryCache的出现意味着传统数据库使用方式的变革吗?(arvin-推荐--看评论)
- 用户故事地图(User Story Mapping)之初体验
- 修改前端HBuilder X软件中字体颜色
- Tree Shaking和sideEffects配置
- php 兼容火狐,HTML_总结CSS中火狐浏览器与IE浏览器的兼容代码,如何让你写的代码更兼容火狐 - phpStudy...
- Q Inventory System unity背包物品插件 使用笔记
- 基于视觉反馈的步进电机X-Y平台控制
热门文章
- Oracle入门(十四.15)之捕获Oracle服务器异常
- 递归算法介绍及Java应用实战
- 分布式一致性算法:可能比你想象得更复杂
- php如何接收前端返回的各种类型的数据
- 拦截器中/* vs /** ------SpringMVC
- 如何评价分类模型性能?(足球荔枝)
- mybatis_user_guide(7) SQL语句构建器类
- 打破双亲委派么,怎么打破_打破了vs你错了
- intellij远程调试_IntelliJ中的远程调试Wildfly应用程序
- jdk 11 模块系统_JDK 9:模块系统状态的重点