RFR: 8366002: Beans.instantiate needs to describe the lookup procedure [v3]

[Alexey Ivanov]

On Sun, 28 Sep 2025 19:41:08 GMT, Phil Race <prr at openjdk.org> wrote:

>> Some text describing the Beans.instantiate lookup process existed only on the method that used the now removed AppletInitializer.
>> Since there are two other Beans.instantiate methods, we need to move that text to the remaining methods.
>> 
>> Note that one of the methods is also deprecated for removal, so it seems prudent to add it to both so that when the next to be removed method is gone, this problem doesn't recur.
>> 
>> This is a doc. only change. The CSR is ready for review.
>
> Phil Race has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8366002

Looks good to me, however, I think it could be improved with marking up example class names and file names with `{@code}`.

src/java.desktop/share/classes/java/beans/Beans.java line 1:

> 1: /*

Should the copyright year be bumped to 2025?

src/java.desktop/share/classes/java/beans/Beans.java line 68:

> 66:      * </p>
> 67:      * The bean is created based on a name relative to a class-loader.
> 68:      * This name should be a {@linkplain ClassLoader##binary-name binary name} of a class such as "a.b.C".

Suggestion:

     * This name should be a {@linkplain ClassLoader##binary-name binary name}
     * of a class such as "a.b.C".

Shall we wrap this line?

Should the names in the quotes be marked up with `{@code}` too?

src/java.desktop/share/classes/java/beans/Beans.java line 81:

> 79:      * try to read a serialized object from the resource "x/y.ser" and if
> 80:      * that failed it would try to load the class "x.y" and create an
> 81:      * instance of that class.

Suggestion:

     * For example, given a {@code beanName} of {@code "x.y"}, {@code Beans.instantiate} would first
     * try to read a serialized object from the resource {@code "x/y.ser"} and if
     * that failed it would try to load the class {@code "x.y"} and create an
     * instance of that class.

I think the example names of the classes and files should be marked up with `{@code}`. This also applies to `".ser"` in the paragraph above.

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

Marked as reviewed by aivanov (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/26905#pullrequestreview-3280120847
PR Review Comment: https://git.openjdk.org/jdk/pull/26905#discussion_r2388191627
PR Review Comment: https://git.openjdk.org/jdk/pull/26905#discussion_r2388171414
PR Review Comment: https://git.openjdk.org/jdk/pull/26905#discussion_r2388188655