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

[Martin Buchholz]

On Tue, Mar 27, 2018 at 8:34 AM, Jonathan Gibbons <
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>
> 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?