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.

          Attachments

            Issue Links

              Activity

                People

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

                  Dates

                  • Created:
                    Updated:
                    Resolved: