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.


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



        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.


            Issue Links



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


                  • Created: