-
Enhancement
-
Resolution: Duplicate
-
P3
-
None
Add a new {@spec} tag to support links to external specs and to nearby JDK specs.
1. General form:
as block tag: @spec url [scope=name] description
as inline tag: {@spec url [scope=name] description}
Note it's a bimodal tag (e.g. like @jls) now that we can support tags like that.
URL can be absolute (i.e. with scheme and domain) or relative (no scheme or domain). Relative links should be evaluated relative to some externally provided base; for JDK docs, relative links could be relative to the base of the `specs/` directory that exists beside the `api/` directory. This will avoid the current use of `<a href="${docRoot}/../specs/...."> style of links.
2. In terms of visual presentation, it expands like @see/{@link} to an HTML <a> element in the obvious manner
3. The description could be put in the search index, in a manner equivalent to {@index "description"}
4. Eventually, all the @spec entries could be collected on a single page, similar to {@systemProperty} and the System Properties page. This External Specifications page should be linked into the main static index page (i.e. at the top of the A-Z index page)
The "scope" option could be used to determine tabs on the table of spec entries.
5. We could search existing docs for HTML <a> elements linking to specific domains, and then convert these elements to use the {@spec} tag.
6. We can cross-reference the list from 5 with the list created for and submitted to the JCP for each release.
7. We could do 1, 2, 5, 6 with a custom JDK tag in the short term (e.g. JDK 16) leaving more advanced features like 3, 4 to later (e.g. JDK 17)
8. doclint could? check the links?
1. General form:
as block tag: @spec url [scope=name] description
as inline tag: {@spec url [scope=name] description}
Note it's a bimodal tag (e.g. like @jls) now that we can support tags like that.
URL can be absolute (i.e. with scheme and domain) or relative (no scheme or domain). Relative links should be evaluated relative to some externally provided base; for JDK docs, relative links could be relative to the base of the `specs/` directory that exists beside the `api/` directory. This will avoid the current use of `<a href="${docRoot}/../specs/...."> style of links.
2. In terms of visual presentation, it expands like @see/{@link} to an HTML <a> element in the obvious manner
3. The description could be put in the search index, in a manner equivalent to {@index "description"}
4. Eventually, all the @spec entries could be collected on a single page, similar to {@systemProperty} and the System Properties page. This External Specifications page should be linked into the main static index page (i.e. at the top of the A-Z index page)
The "scope" option could be used to determine tabs on the table of spec entries.
5. We could search existing docs for HTML <a> elements linking to specific domains, and then convert these elements to use the {@spec} tag.
6. We can cross-reference the list from 5 with the list created for and submitted to the JCP for each release.
7. We could do 1, 2, 5, 6 with a custom JDK tag in the short term (e.g. JDK 16) leaving more advanced features like 3, 4 to later (e.g. JDK 17)
8. doclint could? check the links?
- duplicates
-
JDK-6251738 Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
-
- Resolved
-
- relates to
-
JDK-8255262 Remove use of legacy custom @spec tag
-
- Resolved
-
-
JDK-6251738 Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
-
- Resolved
-
- links to
-
Review openjdk/jdk/790