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

javadoc should support a new @spec tag

    XMLWordPrintable

    Details

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

      Description

      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?

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jjg Jonathan Gibbons
              Reporter:
              jjg Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated: