On 3/27/18 9:07 AM, Martin Buchholz wrote:
On Tue, Mar 27, 2018 at 8:34 AM, Jonathan Gibbons <jonathan.gibb...@oracle.com <mailto:jonathan.gibb...@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.bate...@oracle.com <mailto:alan.bate...@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
