RFR: 8328914: Document the java.security.debug property in javadoc [v9]

[Sean Coffey]

On Tue, 25 Feb 2025 15:32:07 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> Koushik Muthukrishnan Thirupattur has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   8328914: Document the java.security.debug property in javadoc
>
> src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 68:
> 
>> 66:     system property to print additional information:
>> 67: <ul>
>> 68:     <li><code>+thread:</code>Print thread and caller information</li>
> 
> Put `:` outside `<code>`.
> 
> Hi @coffeys and @seanjmullan, now that we have a formal format for options and sub-options, shall we have one for these modifiers? Should it always be appended after the sub-option(s)? Like
> 
> x509:ava+thread,certpath:ocsp,verbose+timestamp+thread
> 
> On the other hand, I'm a little suspicious on the line above. If there is a comma between `oscp` and `verbose`, will it break away from `certpath`? Will `+timestamp` and `+thread` only apply to the `verbose` sub-option?
> 
> Also, how do we specify multiple engines in `provider`? Should it look like this?
> 
> provider:engine=Cipher,Mac
> 
> 
> While this PR is about the doc, I really think we need a test to ensure the format is correctly described.

I'd probably have to point to the CSR that introduced the +thread, +timestamp options :
https://bugs.openjdk.org/browse/JDK-8327569

The "+" symbol should directly follow a valid debug option to be legitimate IMO. It's probably the most intuitive assumption also. 

note that I'd like to switch on `timestamp `and `thread `options by default in a JDK feature release (maybe JDK 25)
They made more sense for the backport (JDK Update) release lines where addition of such meta data might have caused issue for some frameworks parsing this data.

I just logged https://bugs.openjdk.org/browse/JDK-8350689 to track that effort.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970423160