Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8226279

javadoc should support a new @spec tag



    • Type: Enhancement
    • Status: Open
    • Priority: P3
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: 17
    • Component/s: tools
    • Labels:


      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?


          Issue Links



              jjg Jonathan Gibbons
              jjg Jonathan Gibbons
              0 Vote for this issue
              4 Start watching this issue