Bug ID: JDK-8296320 Warn if {@inheritDoc} is ambiguous

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

Other
tbdUnresolved

It would be helpful if javadoc emitted a conditional warning for an ambiguous {@inheritDoc ...} (directed or otherwise).

Such a warning could provide (i) the location of the ambiguous tag (ii) the automatic resolution that javadoc made: that is, the method where documentation was copied from, and (iii) the suggestion on how to eliminate ambiguity.

{@inheritDoc ...} is ambiguous if any of these are true:
 * there are more than one resolution to it (i.e. more than one method to copy documentation from)
 * it resolves to another ambiguous {@inheritDoc ...}

Ambiguity is resolved by automatic documentation algorithm.

The purpose of this RFE is to provide a tool to wean authors off the magic of documentation inheritance, which is not always correct.

It would be worth knowing how common the occurrence of ambiguous inheritance might be.
08-11-2022
The way to "opt out" of the warning is to make the change the code and make the tag unambiguous. This is procedurally similar to the javac warning about ambiguous varargs, # 0: type, 1: type compiler.warn.inexact.non-varargs.call=\ non-varargs call of varargs method with inexact argument type for last parameter;\n\ cast to {0} for a varargs call\n\ cast to {1} for a non-varargs call and to suppress this warning
08-11-2022
Should a user be able to opt out of this warning for a particular area (e.g. a module, package, etc.)? Otherwise, it would mean that it's always suspicious (read: I feel lucky) to use `{@inheritDoc}`, when in fact a particular API might've been carefully designed with the default inheritDoc behavior in mind.
08-11-2022
[~jjg] 1. If there are multiple inheritance paths, but they all lead to the same node, then I agree that it's NOT an ambiguity. 2. For better or worse, JavaDoc has been dealing with documentation inheritance per-element. So, the answer to your question is INDIVIDUAL instances of {@inheritDoc}. So yes, in your example that would be an ambiguity.
03-11-2022
I'm guessing, but it should be clarified explicitly ... Does "ambiguity" refer to the doc comment as a whole, or just the parts that may be referenced by an individual instance of `@inheritDoc`. Consider diamond inheritance where the overrides have some different block tags, but the general description (body) is unchanged. Does that lead to ambiguity in the subtype?
03-11-2022
Ambiguity should refer to multiple _different_ comments (or relevant parts of comments?). If you have diamond inheritance, such that a subtype can inherit the same documentation via different paths, that is not ambiguous enough to warrant a warning.
03-11-2022