[15] RFR JDK-8247785: Small clarification to the javadoc about builtin class loaders

[David Holmes]

Hi Mandy,

The trouble with small clarifications is that they tend to draw 
attention to larger issues :)

On 24/06/2020 7:42 am, Mandy Chung wrote:
> 
> 
> On 6/23/20 12:01 PM, Roger Riggs wrote:
>> Hi Mandy,
>>
>> There may be a missing "to" in:
>>
>> + *     <em>Platform classes</em> are visible the platform class loader
>> ++ *     <em>Platform classes</em> are visible *via* the platform 
>> class loader
>>
> 
> I caught this accidental change too.
> 
>> The second change seems to be self referential using "parent" to 
>> define itself.
>>
>> And pre-existing in the description of getSystemClassLoader:
>>
>> * The platform class loader is a parent or an ancestor of the system 
>> class * loader that all platform classes are visible to it.
>>
>> Is missing "so" in :
>>
>> * loader so that all platform classes are visible to it.
>>
>> Both paragraphs are difficult to read and understand. (  I think the 
>> originals are more readable).
> 
> I made a minor adjustment to break the sentence into two.  That should 
> help.

Reading the javadoc I'm left somewhat confused about the role of the 
Bootstrap class loader versus the Platform class loader these days. What 
classes does the Bootstrap class loader actually load?

> diff --git a/src/java.base/share/classes/java/lang/ClassLoader.java 
> b/src/java.base/share/classes/java/lang/ClassLoader.java
> --- a/src/java.base/share/classes/java/lang/ClassLoader.java
> +++ b/src/java.base/share/classes/java/lang/ClassLoader.java
> @@ -133,8 +133,9 @@
>    *     It is the virtual machine's built-in class loader, typically 
> represented
>    *     as {@code null}, and does not have a parent.</li>
>    * <li><p>{@linkplain #getPlatformClassLoader() Platform class loader}.
> - *     All <em>platform classes</em> are visible to the platform class 
> loader
> - *     that can be used as the parent of a {@code ClassLoader} instance.
> + *     <em>Platform classes</em> are visible to the platform class loader.

That seems somewhat self-defining / tautological.

To me it would be clearer to say something like:

- Platform class loader. This class loader is responsible for loading 
the platform classes. Platform classes include ... The Platform class 
loader can be used as the parent ...

> + *     The platform class loader can be used as the parent of a {@code 
> ClassLoader}
> + *     instance.
>    *     Platform classes include Java SE platform APIs, their 
> implementation
>    *     classes and JDK-specific run-time classes that are defined by the
>    *     platform class loader or its ancestors.
> @@ -152,7 +153,7 @@
>    *     The system class loader is typically used to define classes on the
>    *     application class path, module path, and JDK-specific tools.
>    *     The platform class loader is a parent or an ancestor of the 

s/a/the/

There can only be a single parent, but multiple ancestors.

> system class
> - *     loader that all platform classes are visible to it.</li>
> + *     loader.  It searches and loads the platform classes through its 
> parent.</li>

"It" refers to the system class loader, but the most recent sentence 
subject was the platform class loader, so that makes "it" ambiguous 
here. So I suggest

s/It/The system class loader/

though I'd be tempted to restructure this more:

"The platform class loader is the parent or an ancestor of the system 
class loader, so the system class loader can load platform classes by 
delegating to its parent."

Cheers,
David
-----

>    * </ul>
>    *
>    * <p> Normally, the Java virtual machine loads classes from the local 
> file
> 
> Thanks
> Mandy