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

Generalize see and link tags for user-defined anchors



    • Enhancement
    • Resolution: Fixed
    • P3
    • 20
    • 9
    • tools


      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.



        Issue Links



              hannesw Hannes Wallnoefer
              jjg Jonathan Gibbons
              0 Vote for this issue
              8 Start watching this issue