-
Enhancement
-
Resolution: Fixed
-
P2
-
None
-
b168
-
Not verified
Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
---|---|---|---|---|---|---|
JDK-8179750 | 10 | Kumar Srinivasan | P2 | Resolved | Fixed | b07 |
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.
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.
- backported by
-
JDK-8179750 provide way to link to external documentation
-
- Resolved
-
- blocks
-
JDK-8178412 Doc link updates for i18n
-
- Resolved
-
- relates to
-
JDK-8179915 Update extLink taglet to allow not linking the description
-
- Closed
-