On Mon, 28 Sep 2026 12:55:59 GMT, Jean-Noël Rouvignac <[email protected]> wrote:
>> The example in the class description of `DrbgParameters.Capability` does not
>> compile as written.
>>
>> This patch fixes two issues in the Javadoc example:
>>
>> - `DrbgParameters(-1, requested, null)` → `DrbgParameters.instantiation(-1,
>> requested, null)`.
>> The constructor is private; `instantiation()` is the factory method used
>> by every other
>> example in this file.
>> - `(DrbgParametes.Initiate)` → `(DrbgParameters.Instantiation)`. Class name
>> typo and a
>> nested type that does not exist.
>>
>> Javadoc-only change; no behavior change.
>>
>> ### Testing
>>
>> Copied the example into a standalone program and ran it on JDK 27 (build
>> 27+35) for all
>> three `Capability` values.
>>
>> Original snippet fails to compile:
>> error: cannot find symbol method DrbgParameters(int,Capability,<null>)
>> error: package DrbgParametes does not exist
>>
>> Corrected snippet compiles and the effective capabilities match the table in
>> the Javadoc:
>> PR_AND_RESEED -> PR_AND_RESEED
>> RESEED_ONLY -> RESEED_ONLY NONE -> RESEED_ONLY (one of
>> the allowed values for NONE)
>>
>> <details>
>>
>> ```java
>> import java.security.DrbgParameters;
>> import java.security.DrbgParameters.Capability;
>> import java.security.SecureRandom;
>>
>> public class CapabilityExample {
>> public static void main(String[] args) throws Exception {
>> for (Capability requested : Capability.values()) {
>> SecureRandom s = SecureRandom.getInstance("DRBG",
>> DrbgParameters.instantiation(-1, requested, null));
>> Capability effective = ((DrbgParameters.Instantiation)
>> s.getParameters())
>> .getCapability();
>> System.out.println(requested.name() + " -> " + effective.name());
>> }
>> }
>> }
>>
>> </details>
>>
>> Discussion:
>> https://mail.openjdk.org/archives/list/[email protected]/thread/U24LZRYEMIUT5PIQ6OJZVOKO4Y4G2BJ3/
>>
>> @wangweij Could you take a look? Thanks!
>>
>> ---------
>> - [x] I confirm that I make this contribution in accordance with the
>> [OpenJDK Interim AI Policy](https://openjdk.org/legal/ai).
>
> src/java.base/share/classes/java/security/DrbgParameters.java line 260:
>
>> 258: * The table below lists possible effective values if a certain
>> 259: * capability is requested, i.e.
>> 260: * <blockquote><pre>
>
> Consider using code snippet (https://openjdk.org/jeps/413), this would have
> immediately caught the issue:
> Suggestion:
>
> * {@snippet :
The [JavaDoc Guide on
Snippets](https://docs.oracle.com/en/java/javase/27/javadoc/snippets.html#GUID-3F6C9C7A-659F-408B-BA21-3D37C98B123C)
has:
> The Standard Doclet does not compile or otherwise test snippets; instead, it
> supports the ability of external tools and library code to test them.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/33086#discussion_r4122535169
