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

[Pavel Rappo]

On Thu, 8 Jun 2023 09:18:04 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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.

Have a look at this commit: 3da4f473a7c

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1222709203