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

[Sean Mullan]

On Fri, 7 Mar 2025 19:23:42 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> I think we should look into it. I think we can handle this as a follow-on bug so that we keep this issue just about the docs.
>
> I’m not suggesting any source changes, but this documentation update explicitly states:
>> Sub-options are specified by appending a ":" to the option, followed by a list of one more sub-options separated by a comma.
> 
> This breaks existing usages. In fact, unless (as Seán C suggested) we drop the 2 modifiers entirely and make them always on, I don’t see a good way to fix it later if we keep the current grammar. For example, we might have to hardcode what are options and what are sub-options, so that we can detect that `verbose` here is a sub-option of `certpath` and the comma before it is ignored in the 1st round of string splitting. This would add significant complexity.

Well we are dealing with a syntax that was never specified and is very loosely defined. Either we remove some of the syntax and leave it undefined, or we make sure the syntax works and add more constraints or delimiters, which could break existing usages. But I'm also not sure how much we need to really accommodate corner cases.

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

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