Summary

Update the LocaleServiceProvider documentation to cover deploying an SPI as a module.

Problem

The LocaleServiceProvider specification lacks commentary on deploying as a module. To stay up to date, the class should recommend applications deploy Locale SPIs as a module. This follows the same format as the recent update to the CharsetProvider specification in JDK-8340404.

Solution

Provide commentary and an example that Locale SPIs can be deployed in a module. Additionally, point to ServiceLoader's Deploying Service Providers section for further detail. Lastly, make apparent that Locale SPIs should remain visible to the system class loader.

Specification

In the main class documentation,

  * interfaces to offer support for locales beyond the set of locales
- * supported by the Java runtime environment itself.
+ * supported by the Java runtime environment itself. Locale sensitive service
+ * providers are deployed on the application module path or the application class
+ * path. In order to be looked up, providers must be visible to the {@link
+ * ClassLoader#getSystemClassLoader() system class loader}.
+ * See {@link java.util.ServiceLoader##developing-service-providers Deploying
+ * Service Providers} for further detail on deploying a locale sensitive service
+ * provider as a module or on the class path.
  *
  * <h2>Packaging of Locale Sensitive Service Provider Implementations</h2>
- * Implementations of these locale sensitive services can be made available
- * by adding them to the application's class path. A provider identifies itself with a
- * provider-configuration file in the resource directory META-INF/services,
- * using the fully qualified provider interface class name as the file name.
- * The file should contain a list of fully-qualified concrete provider class names,
- * one per line. A line is terminated by any one of a line feed ('\n'), a carriage
- * return ('\r'), or a carriage return followed immediately by a line feed. Space
- * and tab characters surrounding each name, as well as blank lines, are ignored.
- * The comment character is '#' ('\u0023'); on each line all characters following
- * the first comment character are ignored. The file must be encoded in UTF-8.
+ *
+ * <p> For a locale sensitive service provider deployed in a module, the <i>provides</i>
+ * directive must be specified in the module declaration. The <i>provides</i>
+ * directive specifies both the service and the service provider.
+ *
+ * <p> For example, an implementation of the {@link java.text.spi.DateFormatProvider
+ * DateFormatProvider} class deployed as a module might specify the following directive:
+ * <pre>{@code
+ *     provides java.text.spi.DateFormatProvider with com.example.ExternalDateFormatProvider;
+ * }</pre>
+ *
+ * <p> For a Locale Service Provider deployed on the class path, the provider
+ * identifies itself with a provider-configuration file in the resource directory
+ * META-INF/services. The file name should be the fully fully qualified provider
+ * interface class name. The file should contain a list of fully-qualified concrete
+ * provider class names, one per line. A line is terminated by any one of a line
+ * feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately
+ * by a line feed. Space and tab characters surrounding each name, as well as
+ * blank lines, are ignored. The comment character is '#' ('\u0023'); on each line
+ * all characters following the first comment character are ignored. The file must
+ * be encoded in UTF-8.
  * <p>