8182482: Module System spec updates

[Rony G. Flatscher]

Maybe a few little things:

  * in the Errors section, reason # 4 states:

        The service provider class file has more than one public static no-args method named
        "provider".

    There could be no more than one public static no-args method named "provider" in a class file,
    so this error reason should not be possible?

  * in the "stream" (method-detail) description, second paragraph, second sentence, there is a "the"
    too many:

        If a service provider cannot be loaded for any of *the* *the* reasons...

  * in the "load" (method-detail for: "public static <S> ServiceLoader<S> load​(Class<S> service,
    ClassLoader loader)" ) description, section "Step 1", paragraph starting with "Ordering:", last
    sentence, a "the" is missing "... in same class loader ...", should read: "... in *the* same
    class loader..."

  * Documentation of "Parameters:" in all of the "load" and "loadInstalled" method-details reads:
    "service - The interface or abstract class representing the service", which may wrongly imply
    that  a concrete class may not be supplied; for completeness of the documentation it should
    document that it may be a concrete class as well or just talk about something like: "Class
    representing the service, usually an interface class" to encourage usage of interface classes

  * in the "findFirst" (method-detail) description, second paragraph, second (last) sentence may
    have an "are" too many: "If there are no service providers *are* located then it uses a default
    implementation."

The text explains ServiceLoader very clearly!

---rony

On 20.06.2017 12:20, Alan Bateman wrote:
> We have two javadoc/spec updates that I'd like to get into the JDK 9 Initial Release Candidate
> that is scheduled for this week.
>
> The spec updates are for two issues:
>
> 1. ServiceLoader: The API spec has been updated significantly to support modules but it needs
> another round of update to do clean-up to get it more readable and consistent, and also to align
> it with the JLS.  Most of reorganization and re-wording has been proposed by Alex. Joe Darcy has
> also proposed a few adjustments.
>
> 2. Upgradable modules aren't specified anywhere. Java SE will designate a number of standard
> modules as upgradeable but we don't have anywhere in the docs to link to that or describe how the
> upgraded versions are used in preference to the modules built into the environment.
>
> The webrev with the proposed (docs only, no implementation) changes is here:
>   http://cr.openjdk.java.net/~alanb/8182482/webrev/index.html
>
> The ServiceLoader diffs are hard to read. It might be easier to read the generated javadoc:
> http://cr.openjdk.java.net/~alanb/8182482/docs/java/util/ServiceLoader.html
>
> -Alan