Summary

Update javadoc of ResourceBundle::getBundle(String baseName) and ResourceBundle::getBundle(String baseName, Locale locale) to specify its behavior equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, Module module) where module is the caller's module.

Problem

The javadoc of ResourceBundle::getBundle(String baseName) and ResourceBundle::getBundle(String baseName, Locale locale) specify its behavior equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, ClassLoader loader) where loader is the caller's class loader. It's equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, Module module) where module is the caller's module. It is easier to understand the specification if it's updated to refer to the getBundle variant taking the module parameter.

Solution

Update javadoc of ResourceBundle::getBundle(String baseName) and ResourceBundle::getBundle(String baseName, Locale locale) to specify its behavior equivalent to calling ResourceBundle::getBundle(String baseName, Locale locale, Module module) where module is the caller's module.

In addition, the documentation (ResourceBundle, ResourceBundleProvider, and AbstractResourceBundleProvider class description) is improved to make it clear the several options in deploying resource bundles in modules.

Specification

     /**
      * Gets a resource bundle using the specified base name, the default locale,
-     * and the caller's class loader. Calling this method is equivalent to calling
+     * and the caller module. Calling this method is equivalent to calling
      * <blockquote>
-     * <code>getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())</code>,
+     * <code>getBundle(baseName, Locale.getDefault(), callerModule)</code>,
      * </blockquote>
-     * except that <code>getClassLoader()</code> is run with the security
-     * privileges of <code>ResourceBundle</code>.
-     * See {@link #getBundle(String, Locale, ClassLoader) getBundle}
-     * for a complete description of the search and instantiation strategy.
      *
      * @param baseName the base name of the resource bundle, a fully qualified class name
      * @exception java.lang.NullPointerException
@@ -830,6 +846,9 @@
      * @exception MissingResourceException
      *     if no resource bundle for the specified base name can be found
      * @return a resource bundle for the given base name and the default locale
+     *
+     * @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
+     * @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
      */
     @CallerSensitive
     public static final ResourceBundle getBundle(String baseName)

     /**
      * Gets a resource bundle using the specified base name and locale,
-     * and the caller's class loader. Calling this method is equivalent to calling
+     * and the caller module. Calling this method is equivalent to calling
      * <blockquote>
-     * <code>getBundle(baseName, locale, this.getClass().getClassLoader())</code>,
+     * <code>getBundle(baseName, locale, callerModule)</code>,
      * </blockquote>
-     * except that <code>getClassLoader()</code> is run with the security
-     * privileges of <code>ResourceBundle</code>.
-     * See {@link #getBundle(String, Locale, ClassLoader) getBundle}
-     * for a complete description of the search and instantiation strategy.
      *
      * @param baseName
      *        the base name of the resource bundle, a fully qualified class name
@@ -905,6 +920,9 @@
      * @exception MissingResourceException
      *        if no resource bundle for the specified base name can be found
      * @return a resource bundle for the given base name and locale
+     *
+     * @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
+     * @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
      */
     @CallerSensitive
     public static final ResourceBundle getBundle(String baseName, Locale locale)

Attached is the specdiff for the entire JDK-8193767 doc update which mostly documentation improvement and not a spec change.