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

Issues with javadoc support for preview features

    XMLWordPrintable

Details

    • Bug
    • Resolution: Fixed
    • P3
    • 19
    • 18
    • tools

    Description

      Loom has announced a new preview API, StructuredExecutor. javadoc's preview flagging is looking good -- see https://download.java.net/java/early_access/loom/docs/api/java.base/java/util/concurrent/StructuredExecutor.html -- but two observations:

      1. [Missing anchor] See the paragraph that begins "StructuredExecutor defines the ..." -- the open method has a PREVIEW superscript because the method's declaration refers, in its return type, to a preview API. However, the superscript's link goes to a non-existent anchor, because the method's declaration doesn't have a box announcing preview status (since the method is declared in StructuredExecutor which has a class-level box). We should not generate a PREVIEW superscript for a reference in a preview class to an element in the same preview class. The link to, e.g., join in the same class already has no superscript.
      (If a different class was to link to StructuredExecutor::open then a PREVIEW superscript linking to StructuredExecutor's class-level box would be appropriate.)
      (The PREVIEW superscripts for methods work well in https://download.java.net/java/early_access/loom/docs/api/java.base/java/lang/Thread.html -- see the sentence "The ofPlatform()PREVIEW and ofVirtual()PREVIEW methods are used ..." -- because the superscript links go to the method-level boxes announcing preview status.)

      2. [Missing superscript] Please see the method declaration for fork(Callable<V> task, BiConsumer<StructuredExecutor,Future<U>> onComplete). The type argument StructuredExecutor in that signature should have a PREVIEW superscript which links to #preview-java.util.concurrent.StructuredExecutor.

      Attachments

        Issue Links

          Activity

            People

              jlahoda Jan Lahoda
              jjg Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: