The services section of the module summary page generated by javadoc needs attention.

See the demo src/ and api/ in the attached services.zip file. The command line is

$ javadoc -d services/api --module-source-path services/src --module service,serviceUser,serviceProvider -noindex

Note that in the generated API, the index just shows one of the three modules (service), and not all 3. (See JDK-8190875). However, you can access the docs for all modules using the "Prev Module" "Next Module" links.


There are various comments to note. These may end up being separated into individual issues, with some being deferred to future releases.

1. Blocker: given the following bug, 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.


2. Bug: use of service types in modules not reported.
If the API is generated with the "-use" option, javadoc does not report any uses of the service type Service.
If the API is generated with the "-use -private" options, javadoc does not report any uses of the service implementation type Wonderful.


3. Summary inconsistent with rest of docs

Are the services tables supposed to be "Summary tables" or "Details lists"? In other generated pages, summary tables always/only show first sentence summaries. In these module pages, I think that if there's a @uses or @provides tag with lots of content, it will all show up in the Summary table, right?

Do we need to rethink the presentation of services?


4. Long term wish list item.

Despite the fact that the serviceUser and serviceProvider modules use the service type "Service", there is nothing on the doc page for the Service class to show such usage.

By analogy with "Functional interfaces", if we have enough info to determine that a type is being mentioned as a service type, we could add text to the class' page saying something like "This is a service type. Instances of this class may be obtained from the service loader". Or something like that.

By analogy with other classes and "All Known Implementing Classes:", if we have enough info, we could include a list "All Known Modules Providing Service Implementations". Or something like that.