On Tue, 25 Feb 2025 00:29:35 GMT, Koushik Muthukrishnan Thirupattur <d...@openjdk.org> wrote:
>> java.security.debug is a widely used debug system property for JDK security >> libs. It's time to capture details about this property via javadoc. >> >>  >> >> >> NOTE : We are adding a new html file (similar to the Networking Properties >> [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/net/doc-files/net-properties.html#networking-properties-heading)) >> for documenting security-related properties, and over time, we will add >> more properties to this page. > > 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 29: > 27: <head> > 28: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> > 29: <title>Security-Related System Property</title> Not what I expected. Either you keep the old name and add a few new system properties, or, just change the whole title to something like "Troubleshooting" or "Printing Debug Information". src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 58: > 56: and therefore are best set using the <code>-D</code> option of the > java command, > 57: while others have a more dynamic nature and can also be changed using > 58: the <a > href="../../lang/System.html#setProperty(java.lang.String,java.lang.String)">System.setProperty()</a> > API. The `System.setProperty()` call should be in `<code>`. src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 63: > 61: <H2>Debug</H2> > 62: <p><B>{@systemProperty java.security.debug}</B><BR></p> > 63: <H2>Printing Thread and Timestamp Information</H2> This is still a big `<H2>`, which is at the same level as `<H2>Debug</H2>`. 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 Also, how do we specify multiple engines in `provider`? Should it look like this? provider:engine=Cipher,Mac src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 74: > 72: For example, to add thread, caller, and timestamp information to all > debuging output, > 73: set the <code>java.security.debug</code> system property on the > command line as follows:<br> > 74: <code>java -Djava.security.debug=all+thread+timestamp MyApp</code> For the code in its own paragraph, should it be something like `<pre>`? src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 79: > 77: which determines what trace messages are printed during > execution. The value of the property is one or more options separated by a > comma. > 78: Some options also have additional sub-options. Sub-options > are specified by appending a ":" to the option, followed by a list of one > more sub-options separated by a comma. > 79: For example, to specify the <code>ocsp</code> and > <code>verbose</code> options with the <code>certpath</code> option: set the > property to <code>"certpath:ocsp,verbose"</code>. Do we need `"` inside `<code>`? src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 94: > 92: <tr> > 93: <th scope="row"><code>all</code></th> > 94: <td><code>Turn on all the debugging options</code></td> Remove `<code>` from the line above. src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 102: > 100: <ul> > 101: <li><code><b>ocsp:</b></code> Dump OCSP protocol > exchanges</li> > 102: <li><code><b>verbose:</b></code> Print additional > debugging information</li> Move `:` out of `<code>`. src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 128: > 126: <tr> > 127: <th scope="row"><code>KeyStore</code></th> > 128: <td><code>Keystore</code> debugging</td> it's `KeyStore`. src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 157: > 155: <th scope="row"><code>provider</code></th> > 156: <td>Security provider debugging. The following engines can be > used with the <code>`provider`</code> sub-option: > 157: <code>`engine=(engines)`</code> : The output is displayed > only for a specified list of JCA engines. Remove extra "`". src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 190: > 188: <tr> > 189: <th scope="row"><code>x509</code></th> > 190: <td><code>X.509</code> certificate debugging. You can use the > following sub-option with <code>X.509</code> No need for "X.509" in `<code>`. src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 192: > 190: <td><code>X.509</code> certificate debugging. You can use the > following sub-option with <code>X.509</code> > 191: <ul> > 192: <li><code><b>ava:</b></code> Embed > non-printable/non-escaped characters in AVA components as hex strings</li> Move `:` out of `<code>`. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970006546 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970034740 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970008007 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970023633 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970055051 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970051804 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970053286 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970059952 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970056086 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970057231 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970058092 PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1970059105
