Bug ID: JDK-6934301 Support directed inheriting of class comments with @inheritDoc

Type: Enhancement
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 7

Priority: P3
Status: In Progress
Resolution: Unresolved
OS: generic
CPU: generic

Submitted: 2010-03-11
Updated: 2022-12-15

JDK 21
21Unresolved

The utility of @inheritDoc would be improved if documentation from supertypes could be selectively inherited for a class or interface declaration in addition to information for methods.  This would greatly ease the maintenance of javadoc for many kinds of APIs.

For example, it would be helpful to be able to write javadoc like the following:

/**
 * All about A.
 */
class A {...}

/**
 * Some specific information about B.
 * {@inheritDoc A}
 * Some more information specific to B.
 * {@inheritDoc I}
 */
class B extends A implements I {...}

As an experiment, I would find it interesting if the JDK docs build generated "Note:"'s when an ambiguity was found.
13-04-2022
[~darcy], I understand that. I should've clarified that I was commenting solely on generating errors/warnings. We already provide automatic inheritance for method comments. It does not produce warnings, let alone errors, when there's an ambiguity; instead, it uses a disambiguating algorithm. It's a separate issue if this algorithm is adequate or not. All I wanted to say is that if we decide to provide automatic inheritance for _interface_ comments, there's no reason for it to behave differently in the face of ambiguity. Either both algorithms should generate warnings or neither. An error is better as we don't need to put anything in the documentation; we just stop. A warning is more forgiving. Regardless of what we choose -- a warning or silence -- we need something to put in the generated document.
13-04-2022
[~prappo], yes, precisely why I filed this RFE!
12-04-2022
[~darcy], a declaration of an interface that extends multiple interfaces is similar to a declaration of a method that overrides multiple superinterface methods in the sense that they are ambigous wrt documentation inheritance. Consider `BlockingDeque.add(E)`. Which tag should `@throws IllegalStateException {@inheritDoc}` inherit? The one that is defined in `BlockingQueue.add(E)` or the one that is defined in `Deque.add(E)`?
12-04-2022
[~prappo], I assume changing this is just a "{$SIZE} matter of programming"? Perhaps only enabled only with explicit indication of where the inheritance should come from. e.g. /** {@inheritDoc} / // Error interface C extends A, B { } /* {@inheritDoc A} */ // Fine interface C extends A, B { }
12-04-2022
[~darcy], just to clarify what I meant. I mean class and interface declarations, not method declarations. This is about JDK-8008768 and my earlier findings. This works: /** {@inheritDoc} / class B extends A { } This does NOT work: /* {@inheritDoc} */ interface B extends A { }
12-04-2022
There are multiple examples in the javax.lang.model packages of inheritDoc working as desired for interface methods, see Element and TypeMirror.
12-04-2022
FWIW, @inheritDoc is not effective on interface declarations, it only works on class declarations.
11-04-2022
UPDATE ====== My previous comment assumed that `{@inheritDoc}` did not work with type declarations. I thought that trying to document source like this would fail: ``` /** * This is a top-level comment for MyType. / public class MyType { } /* * {@inheritDoc} / public class MySubType extends MyType { } ``` You see, https://docs.oracle.com/en/java/javase/15/docs/specs/javadoc/doc-comment-spec.html#comment-inheritance defines comment inheritance on methods only*; also `{@inheritDoc}` on a type declaration does not seem to occur anywhere in the JDK code base (neither have I ever seen it anywhere outside JDK). But today I checked whether `{@inheritDoc}` works with type declarations. To my surprise it did! I then went ahead and checked that behavior for JDKs from 1.3 through 1.8. What I found suggests that sometime between JDKs 1.7 and 1.8 this warning disappeared and javadoc started to bake in the inherited documentation: "warning - Tag @inheritDoc cannot be used in class documentation. It can only be used in the following types of documentation: method, inline text." I'll try to pinpoint the exact changeset that did that; this is important for tracking the feature evolution and improving the test coverage. Perhaps we would also want to describe the actual behavior in the "Documentation Comment Specification for the Standard Doclet" mentioned above.
20-01-2022
Found it: JDK-8008768; https://git.openjdk.java.net/jdk/commit/4b44fd76225deb12588ccb70849f1c6ad1432e4e
22-10-2020
I think there are two issues here. The first issue is allowing explicit inheritance of doc comments on type declarations. The second issue is extending `{@inheritDoc}` such that it would allow to specify a particular edge in an inheritance graph, for instance: `{@inheritDoc ref}`. Inheritance on Type Declarations ================================ 1. Are there any good examples in the JDK where this would be useful? 2. What about implicit comment inheritance (through a blank doc comment)? Should it work similarly to how it works for methods? Directed Inheritance ==================== 1. While I have no issues with directed inheritance, I don't see the benefits of providing multiple references as well as the "default" marker. In order for {@inheritDoc A B C} to be a win compared to {@inheritDoc A} {@inheritDoc B} {@inheritDoc C} cases like that should be typical, which I don't think is the case. It looks like a corner case instead.
31-08-2020
"The default capability" means "{@inherit default}" should be the same as the current "{@inheritDoc}" behavior. Note that since `default` is a Java keyword, it cannot be the name of any normal super type. (Standard disclaimer about JVMS names.) By itself, this might seem redundant, but it might be useful in the case where additional super types are listed. "{@inherit A B C default}"
19-08-2020
[~jjg] Jon, could you elaborate on "default" capability?
18-08-2020
Useful outline of the proposed feature. I think the "default" capability would be useful too.
13-08-2020
This implies a small but significant change in InheritDocTree, and hence probably needs to be done with default methods, and will require a CSR. Ideally, doclint would validate the names, reporting any issues in the REFERENCE category. I'm assuming the informal spec is that `{@inheritDoc}` should be updated to support `{@inheritDoc class-or-interface-name(s)}`. If we decide to support multiple names, it should (informally) be equivalent to repeating the tag with each name in turn. If we decide to support multiple names, it may be useful to allow `default` to reference the existing behavior, when no name is specified. Apart from the possible `default` case, the names should identify super types, as either fully qualified names or imported names. It's not clear that we need to support `module/type` syntax, because there can never be two super types with the same name from different modules. If using the tag on a method, the names must refer to supertypes that explicitly provide the same method signature. (covariant overrides allowed)
13-08-2020
We should also consider the possibility of referencing the spec in multiple super types.
12-02-2018
EVALUATION This would be a nice feature enhancement. Currently, the javadoc only inherites from one supertype. We will need to modify the @inheritDoc to accept the supertype from which the documentation can be inherited.
09-11-2010

Relates :	JDK-4738591 - stddoclet: Allow {@inheritDoc} to work with more tags
Relates :	JDK-4810216 - Allow {@inheritDoc name} for constructors
Relates :	JDK-6386502 - allow more flexible inclusion and cross referencing of doc comments
Relates :	JDK-8285368 - Overhaul doc-comment inheritance
Relates :	JDK-4957169 - Please provide full details about where a method is specified in multiple-inheritance interfaces
Relates :	JDK-6376959 - Algorithm for Inheriting Method Comments seems to go not as documented