JDK-4318797 : Add tag to specify re-use of method comments
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.3.0
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • OS: generic
  • CPU: generic
  • Submitted: 2000-03-04
  • Updated: 2022-01-21
  • Resolved: 2000-11-15
Related Reports
Duplicate :  
Description
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).

Comments
EVALUATION Copied the text of this RFE to 4186639 and closed this out as dupe. This RFE basically requests that there be an explicit tag (such as @inheritdoc), so that the DocCheck doclet could distinguish doc comments intentionally inheriting docs from those unintentionally inheriting docs (they currently both appear blank). I disagree with his first disadvantage and his comment that "javadoc could omit the warnings about the text being copied." This is necessary even if the text is copied. I agree, as long as we don't *require* such a tag -- that is, javadoc should continue copying comments automatically even if the tag is missing. This maintains backward compatibility and makes the docs much more useful, as copying the doc comment is what needs to be done in most cases, including the default case. doug.kramer@Eng 2000-11-15
15-11-2000