Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8190237 Services section in the module summary page should provide correct documentation
  3. JDK-8192007

javadoc @uses and @provides tags in the modules documentation appears before the first-sentence summary of the service type.

    Details

    • Type: Sub-task
    • Status: Resolved
    • Priority: P3
    • Resolution: Fixed
    • Affects Version/s: 9
    • Fix Version/s: 10
    • Component/s: tools
    • Labels:
      None

      Backports

        Description

        We can't realistically use @uses, @provides in JDK modules.

        The text from the @uses and @provides tags in the module's doc comment appears before the first-sentence summary of the service type. This doesn't make any semantic sense. See the attached "services" example, which is a demo with somewhat realistic comments, to help demonstrate the silliness. See the module summary page for the serviceUser and serviceProvider modules. In both cases, the juxtaposition of the two pieces of text makes no sense.

        In serviceUser, it might make sense to flip the order (first sentence of service type before @uses text.) It might make even more sense to just use the @uses text if given, and to fall back on the first-sentence of the service type if no @uses text given.

        In serviceProvider, it is not clear that it is ever helpful to include the first sentence of the service type's documentation.

        Somewhat related, the style of the two text fragments is different. It would seem to make more sense for the same style to be used for everything appearing in the Description column.

          Activity

          Hide
          bpatel Bhavesh Patel added a comment -
          The ModuleWriterImpl.java needs to be updated to provide correct description text.
          Show
          bpatel Bhavesh Patel added a comment - The ModuleWriterImpl.java needs to be updated to provide correct description text.
          Hide
          hgupdate HG Updates added a comment -
          URL: http://hg.openjdk.java.net/jdk/jdk10/rev/dd3b97564ed7
          User: bpatel
          Date: 2018-01-04 17:27:02 +0000
          Show
          hgupdate HG Updates added a comment - URL: http://hg.openjdk.java.net/jdk/jdk10/rev/dd3b97564ed7 User: bpatel Date: 2018-01-04 17:27:02 +0000

            People

            • Assignee:
              bpatel Bhavesh Patel
              Reporter:
              bpatel Bhavesh Patel
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: