Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4318797

Add tag to specify re-use of method comments

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Duplicate
    • Icon: P4 P4
    • None
    • 1.3.0
    • tools

      According to the 1.3 javadoc documentation: If a method m1() in a class or interface has no doc comment or tags, Javadoc will instead use the comment and tags from method m2() it either overrides or implements, if any.

      This is a helpful feature, but the fact that it's based on the lack of information has two disadvantages: First, it caused the designers of the feature to add text "Description copied from class" and "Following copied from class" to the inherited documentation, to warn readers that this isn't "real" documentation. Second, documentation checker tools will still flag the method as undocumented, because they can't know whether the lack of documentation is intentional or not.

      It would be better to have an explicit tag that requests comment re-use. Given such a tag, javadoc could omit the warnings about the text being copied, and documentation checkers could accept the tag as complete documentation. The tag could also specify from which interface the documentation should be inherited, if the same method is specified in multiple interfaces.

      I would just have one tag (@inherit-docs or similar), but since javadoc currently distinguishes between the description and the tags, you might have two instead (@inherit-description and @inherit-tags or similar).

            dkramersunw Douglas Kramer (Inactive)
            nlindenbsunw Norbert Lindenberg (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: