Up to now, we have typically linked to "external" documentation using hacks like {@docRoot}/.. and -XdocRootParent.

In JDK 9, with the proposed docs layout, this will no longer work.

The proposal is a new taglet to encapsulate external links such that the actual target of the link can be provided/adjusted at build time, and is not bound into the doc comments.

The proposed tag is
    {@extLink name description}

A build-time taglet could turn this into
   <a href="URL">description</a>
where the URL is determined from the name. This could be done with a table lookup or by computing the URL, perhaps using a query string containing the name. A default taglet could ignore the name and just write out something like
    <span class="externalReference">description</span>
(i.e. no link) This last suggestion may be more appropriate for IDE-like environments that want to interactively present the doc comment to the user.