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

[Sean Mullan]

On Mon, 24 Feb 2025 20:01:13 GMT, Koushik Muthukrishnan Thirupattur <duke at 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.
>> 
>> ![image](https://github.com/user-attachments/assets/f36a1d8c-3026-4a72-a9e8-b2ecdbf9ed42)
>> 
>> 
>> 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 65:

> 63:         <p> To monitor security access, you can set the <code>java.security.debug</code> system property,
> 64:             which determines what trace messages are printed during execution. The value of the property is one or more options separated by a comma.
> 65:             Some options also have additional sub-options; see the list below for more details on the syntax of each.

Do we want to state a syntax for sub-options? The implementation is very flexible, it just searches for the sub-option. But I think the de-facto syntax is the option, a ":" and then a list of one more more sub-options separated by a comma. Ex: java.security.debug=certpath:ocsp,verbose

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 141:

> 139:     <tr>
> 140:         <th scope="row"><code>provider</code></th>
> 141:         <td>Security provider debugging. The following engines can be used with the `provider` sub-option:

Does markdown get rendered in code font here, ex: `provider`?

src/java.base/share/classes/java/security/doc-files/security-related-system-properties.html line 175:

> 173:     <tr>
> 174:         <th scope="row"><code>x509</code></th>
> 175:         <td>X.509 certificate debugging. You can use the following sub-option with X.509

s/with X.509/with <code>x509</code>:/

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1968404844
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1968408603
PR Review Comment: https://git.openjdk.org/jdk/pull/23569#discussion_r1968407990