主要观点:
- 介绍了 JDK 工具和实用程序中 javadoc 工具关于方法注释重用的规则,在不需要时使用
{@inheritdoc}
明确描述注释继承是不必要的,因为相同的注释会隐式继承。 - 通过简单代码示例说明 javadoc 方法注释继承的一些关键规则,包括从父类和实现的接口中隐式继承注释,以及使用
{@inheritdoc}
显式声明继承。 - 展示了不同类(如
dog
、cat
、horse
等)在继承和实现过程中如何处理方法注释,以及生成的 javadoc 文档的情况。 - 得出结论,编写 javadoc 时应在较高层次定义通用注释,让自动继承发挥作用,避免在继承和实现层次结构中重复复制和粘贴相同的注释。
关键信息:
- 提供了多个接口(
herbivorous
、carnivorous
、omnivorous
等)和类(animal
、mammal
、dog
等)的代码示例,用于演示方法注释的继承。 - 引用了 Javadoc 工具文档中的相关内容,如“method common inheritance”和“automatic copying of method comments”。
- 展示了不同类的 javadoc 文档在浏览器中的呈现情况,包括继承的注释、
{@inheritdoc}
的使用以及具体方法的注释细节。
重要细节:
{@inheritdoc}
用于明确表示应继承注释,它可以插入到方法的主描述或@return
、@param
、@throws
标签注释中。- javadoc 注释在父类方法和实现的接口方法中隐式继承,当没有指定文本(没有 javadoc 或空的
/** */
)时。 - 可以在方法注释的不同位置使用
{@inheritdoc}
标签来实现方法文档的隐式和显式继承。 - 不同的 Java IDE(如 NetBeans、IntelliJ IDEA、Eclipse 和 JDeveloper)支持遵循相同方法文档继承规则的 javadoc 呈现。
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。