RFR: JDK-8284851 Update javax.crypto files to use proper javadoc for mentioned classes [v2]

[Mark Powers]

On Tue, 28 Jun 2022 20:58:17 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> Mark Powers has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Valerie fix
>
> src/java.base/share/classes/java/security/Policy.java line 505:
> 
>> 503:      * <p> A new {@code Policy} object encapsulating the
>> 504:      * {@code PolicySpi} implementation from the specified Provider
>> 505:      * object is returned.  Note that the specified Provider object
> 
> Provider, twice.

Changed to "provider".

> src/java.base/share/classes/java/security/Policy.java line 517:
> 
>> 515:      * {@code null}.
>> 516:      *
>> 517:      * @param provider the Provider.
> 
> Provider.

used `{@code Provider}`

> src/java.base/share/classes/java/security/Policy.java line 581:
> 
>> 579:      * Otherwise this method returns {@code null}.
>> 580:      *
>> 581:      * @return the Provider of this Policy, or {@code null}.
> 
> Provider, L575/577/581. Maybe "provider". Or wrap in code.

Fixed.

> src/java.base/share/classes/java/security/Policy.java line 596:
> 
>> 594:      * Otherwise this method returns {@code null}.
>> 595:      *
>> 596:      * @return the type of this Policy, or {@code null}.
> 
> Policy, L590/596.

Fixed.

> src/java.base/share/classes/java/security/Policy.java line 611:
> 
>> 609:      * Otherwise this method returns {@code null}.
>> 610:      *
>> 611:      * @return Policy parameters, or {@code null}.
> 
> Policy, L605/611.

used `{@code Policy}`

> src/java.base/share/classes/java/security/ProtectionDomain.java line 53:
> 
>> 51:  * policies, a {@code ProtectionDomain} can also be constructed such that it
>> 52:  * is dynamically mapped to a set of permissions by the current Policy whenever
>> 53:  * a permission is checked.
> 
> Policy, L50/52.

used "policy"

> src/java.base/share/classes/java/security/ProtectionDomain.java line 166:
> 
>> 164:      * Permissions object.
>> 165:      * <p>
>> 166:      * The permissions granted to this domain are static, i.e.
> 
> CodeSource, Permissions. Note it's PermissionCollection here. So maybe use "permissions".

used "permissions"

> src/java.base/share/classes/java/security/ProtectionDomain.java line 192:
> 
>> 190:     /**
>> 191:      * Creates a new {@code ProtectionDomain} qualified by the given CodeSource,
>> 192:      * Permissions, ClassLoader and array of Principals. If the
> 
> Same as above, plus ClassLoader and Principal.

Fixed.

> src/java.base/share/classes/java/security/ProtectionDomain.java line 241:
> 
>> 239:     /**
>> 240:      * Returns the CodeSource of this domain.
>> 241:      * @return the CodeSource of this domain which may be {@code null}.
> 
> CodeSource.

used `{@code Codesource}`

> src/java.base/share/classes/java/security/ProtectionDomain.java line 251:
> 
>> 249:     /**
>> 250:      * Returns the ClassLoader of this domain.
>> 251:      * @return the ClassLoader of this domain which may be {@code null}.
> 
> ClassLoader.

used `{@code ClassLoader}`

> src/java.base/share/classes/java/security/ProtectionDomain.java line 298:
> 
>> 296:     /**
>> 297:      * Check and see if this {@code ProtectionDomain} implies the permissions
>> 298:      * expressed in the Permission object.
> 
> Permission.

used `{@code Permission}`

> src/java.base/share/classes/java/security/ProtectionDomain.java line 458:
> 
>> 456:      *          debug is {@code null},
>> 457:      *          caller has Policy.getPolicy permission
>> 458:      */
> 
> Maybe it's not necessary to fix these non-public API cases.

IntelliJ will certainly generate javadoc for non-public cases.

> src/java.base/share/classes/java/security/ProviderException.java line 52:
> 
>> 50: 
>> 51:     /**
>> 52:      * Constructs a {@code ProviderException} with the specified detail
> 
> String, L43/53. I'm now wondering if we need to describe what detail message means at all.

I'm going to keep `{@code String} `since I don't want to go back and change all occurrences in all files. Documentation changes are too subjective and destroy the brain.

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

PR: https://git.openjdk.org/jdk/pull/9282