RFR: JDK-8277028: Use service type documentation as fallback for @provides

[Hannes Wallnöfer]

On Mon, 15 Nov 2021 11:25:09 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> This is a simple change to display the first sentence of the service type description in the "Provides" section of a module page if the `@provides` javadoc tag does not contain a description. This is the same we handle entries in the "Uses" section when no description is available from the `@uses` tag. The rationale is that it is still more useful to provide generic information about the service type than nothing if no provider-specific information is available.

Thanks for the review!

> I was not familiar with this part of JavaDoc. When comparing source and documentation of the JDK, I was somewhat surprised to discover that aside from tests, neither `@uses` nor `@provides` specifies the optional description.

Well the tags are documented in the "Documentation Comment Specification for the Standard Doclet", but both `@uses` and `@provides` are used without description in a lot of code bases (including JDK). I think the reason for this is that descriptions in those tags used to be displayed *in addition* to the first sentence from the service documentation, which I think looked kind of wrong. See [JDK-8192007](https://bugs.openjdk.java.net/browse/JDK-8192007) for details.

-------------

PR: https://git.openjdk.java.net/jdk/pull/6387