继承 Javadoc 方法注释

主要观点:

  • 介绍了 JDK 工具和实用程序中 javadoc 工具关于方法注释重用的规则,在不需要时使用{@inheritdoc}明确描述注释继承是不必要的,因为相同的注释会隐式继承。
  • 通过简单代码示例说明 javadoc 方法注释继承的一些关键规则,包括从父类和实现的接口中隐式继承注释,以及使用{@inheritdoc}显式声明继承。
  • 展示了不同类(如dogcathorse等)在继承和实现过程中如何处理方法注释,以及生成的 javadoc 文档的情况。
  • 得出结论,编写 javadoc 时应在较高层次定义通用注释,让自动继承发挥作用,避免在继承和实现层次结构中重复复制和粘贴相同的注释。

关键信息:

  • 提供了多个接口(herbivorouscarnivorousomnivorous等)和类(animalmammaldog等)的代码示例,用于演示方法注释的继承。
  • 引用了 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 呈现。
阅读 9
0 条评论