RFR: {@docRoot} reference need to be updated to reflect new module structure

[Martin Buchholz]

On Tue, Mar 27, 2018 at 2:00 AM, Alan Bateman <Alan.Bateman at oracle.com>
wrote:

> On 27/03/2018 01:01, Jonathan Gibbons wrote:
>
>> This is fixing up some links in the java.base module, following a recent
>> change
>> in javadoc to the organization of the generated files. While the change
>> was mostly
>> transparent, links within the documentation using {@docRoot} need to be
>> updated.
>>
> Looks okay to me. I assume Doug or Martin will need to update the
> java.util.concurrent classes in the jsr166 CVS too.


Yes, this will cause some work for us, but go ahead and submit.
These references with docRoot have always been trouble, since they're very
brittle.
Can't we fix these for real in the javadoc tool itself by by introducing a
variant of @link that works for any anchor?!

{@linkplain Collection#optional-restrictions optional}

(You can fiddle with the syntax)
Something like this should be easier to implement than all the docRoot
fiddling we've been doing over the years.