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

[Jonathan Gibbons]

On 3/27/18 8:30 AM, Martin Buchholz wrote:

>
>
> On Tue, Mar 27, 2018 at 2:00 AM, Alan Bateman <Alan.Bateman at oracle.com 
> <mailto: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.

Martin,

Thanks for the review, and yes, the same desire to avoid these 
{@docRoot} links has already occurred to use.

One suggestion that has been proposed is '##', such that

     {@link package.class#member}

works as before, but

     {@link package.class##id}

would allow references to user-defined anchors.

-- Jon