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

[Jonathan Gibbons]

On 3/27/18 9:07 AM, Martin Buchholz wrote:
>
>
> On Tue, Mar 27, 2018 at 8:34 AM, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>     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.
>
>
> That syntax seems reasonable.  I don't have a strong feeling about how 
> to do it.  As always with software, there are details to worry about.  
> Unlike with @link there's no generated text, so caller must provide 
> the text to be linkified. Maybe only linkplain should be supported.  
> Maybe if  there's no ambiguity and we can use a single '#' and using a 
> '-' in the id guarantees no ambiguity?
>

JDK-8200337

-- Jon