-
Enhancement
-
Resolution: Fixed
-
P3
-
9
-
b23
It would be good to generalize @see and {@link} to be able to link to user-defined anchors within the documentation without having to use explicit HTML `<a href=...>` and/or {@docRoot}.
There are various aspects to this.
1. Referring to user-defined anchors on generated pages for elements (types, packages and modules.)
This is a generalization of JDK-4758314.
2. Referring to user-defined anchors on additional pages, such as doc-files pages.
The first is (mostly) just about the syntax of identifying the position within the page, although there is an implication to be able to nominate links on package and module pages. There are two suggestions:
a. Use a new separator `##` for user-defined names. package.class##name
b. Coexist with the existing separator `#` for user-defined names, but introduce a convention to avoid name clashes with the names of any members. The convention could be to allow/use non-identifier characters, such as `-`. E.g. `myPackage.MyClass#my-anchor`.
The second issue is about identifying files in user-defined subdirectories of packages.
One proposal is retain the same syntax to identify a module/package/class, but allow a relative path when a user-defined anchor is specified, such as `myPackage.MyClass##doc-files/myFile.html#my-anchor`.
A different direction would be have a different taglet, similar to {@docRoot} that expands to the path for a package. This could be combined with standard HTML syntax for a link:
<a href="{@packageRoot myPackage.MyClass}/doc-files/myFile.html#my-anchor">...</a>
The advantage is that this minimizes the amount of special new syntax for describing arbitrary links.
There are various aspects to this.
1. Referring to user-defined anchors on generated pages for elements (types, packages and modules.)
This is a generalization of JDK-4758314.
2. Referring to user-defined anchors on additional pages, such as doc-files pages.
The first is (mostly) just about the syntax of identifying the position within the page, although there is an implication to be able to nominate links on package and module pages. There are two suggestions:
a. Use a new separator `##` for user-defined names. package.class##name
b. Coexist with the existing separator `#` for user-defined names, but introduce a convention to avoid name clashes with the names of any members. The convention could be to allow/use non-identifier characters, such as `-`. E.g. `myPackage.MyClass#my-anchor`.
The second issue is about identifying files in user-defined subdirectories of packages.
One proposal is retain the same syntax to identify a module/package/class, but allow a relative path when a user-defined anchor is specified, such as `myPackage.MyClass##doc-files/myFile.html#my-anchor`.
A different direction would be have a different taglet, similar to {@docRoot} that expands to the path for a package. This could be combined with standard HTML syntax for a link:
<a href="{@packageRoot myPackage.MyClass}/doc-files/myFile.html#my-anchor">...</a>
The advantage is that this minimizes the amount of special new syntax for describing arbitrary links.
- csr for
-
JDK-8294195 Generalize see and link tags for user-defined anchors
- Closed
- relates to
-
JDK-4758314 stddoclet: Add ability to jump/link to user anchor on class/package page w/o giving filename
- Open
-
JDK-8300133 Use generalized see and link tags in core libs
- Resolved
-
JDK-8300321 Use link tags in javax.sql.rowset package-info
- Resolved
-
JDK-8300594 Use generalized see and link tags in UnicastRemoteObject
- Resolved
-
JDK-8289332 Auto-generate ids for user-defined headings
- Resolved
(1 relates to, 2 links to)