RFR: 8285368: Overhaul doc-comment inheritance [v2]

[Pavel Rappo]

On Wed, 7 Jun 2023 20:23:09 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   feedback: make warning less scary
>
> test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java line 75:
> 
>> 73:         // code is OK, it likely isn't (after all, there's an unknown tag).
>> 74:         setAutomaticCheckNoStacktrace(true);
>> 75:         { // DocLint is on
> 
> "on" -> "explicit"

Done in 93adde63ed0.

> test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java line 85:
> 
>> 83:             }
>> 84:         }
>> 85:         // DocLint is off
> 
> "off" -> "default"

Done in 93adde63ed0.

> test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java line 289:
> 
>> 287: 
>> 288:     /*
>> 289:      * C1.m inherits documentation from B1.m explicitly and undirect.
> 
> possible typo: do you mean "indirect"

I'm neither a grammarian nor a native English speaker, but my hunch is that _indirect_ would be wrong here. But again, I'm open to corrections.

I believe "directed inhertiance" came from an analogy with the graph theory, where a graph can be directed and undirected. The former has pointy arrows, the latter does not.

By that analogy, documentation inheritance can be directed `{@inheritDoc <FQN>}` (I choose), or undirected `{@inheritDoc}` (JavaDoc chooses / I'm Feeling Lucky). In addition to that, documentation inheritance can be implicit (i.e. by omission), which works the same way as undirected but without extra keystrokes.

While those concepts are lacking better names, can I suggest we use the following almost-made-up adverbs: _directedly_ and _undirectedly_? As a side note, we badly need a JavaDoc vocabulary.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222703693
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222703773
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222700845