JDK-4160540 : stddoclet: Need to tell if doc comment that inherits doc is intentionally blank
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.0
  • Priority: P5
  • Status: Closed
  • Resolution: Duplicate
  • OS: solaris_2.6
  • CPU: generic
  • Submitted: 1998-07-24
  • Updated: 2014-05-05
  • Resolved: 2002-11-25
Related Reports
Duplicate :  
JDK-4186639 - stddoclet: Inherit documentation with {@inheritDoc} tag
Description
For methods that implement an interface, the DocCheck utility
generates comments of the form:
   // implements path.to.NameOfInterface 

That's good as far as it goes. Once these comments are added,
JavaDoc and DocCheck have no way to see them, so subsequent
runs contine to report them as errors.

DocCheck has a switch that allows the generated comments to
be turned off -- but using that switch means that if a method
is added at a later date, it won't be found.

A comment of the form /** @inheritsCommentsFrom path.to.TheInterface */
would solve things nicely. JavaDoc could either ignore the
implements clause, or verify that the specified interface is
correct. In either case, the DocCheck utility would know that
the method is properly documented.

(Originally the requested tag was named @implements 
-dkramer)
Comments
EVALUATION I am dubious that humans should be entering comments of this form when javadoc has the needed info. Comments... robert.field@Eng 1998-07-27 I'm not sure Robert understood the request. I have gotten further clarification from Eric and entered that under "Comments". In any case, it seems like a low priority bug, because even if we implemented this, it seems unlikely many engineers would actually use it, though some would. doug.kramer@Eng 2000-11-02 This has been implemented as /** * {@inheritDoc} */ This has the same effect for fields and methods (but not constructors) as omitting the comment entirely. However, I don't it's necessary to expect programmers to add such a comment to the code simply to avoid "missing comment" warnings in DocCheck. A better approach would be for DocCheck to use the same algorithm that the standard doclet uses to determine whether a comment would be inherited. Then if it actually inherits a comment, it would not need to mark the comment as missing. Closing out as duplicate of 4186639 "inherit documentation with {@inheritDoc} tag". ###@###.### 2002-11-24
24-11-2002