JDK-8214559 : Use {@systemProperty} for definitions of system properties
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.util.concurrent
  • Affected Version: 12
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2018-11-30
  • Updated: 2018-12-14
  • Resolved: 2018-12-12
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 12
12 b24Fixed
Related Reports
Relates :  
JDK-8211132 - Support {@systemProperty } tag
Relates :  
JDK-8215326 - Test java/util/concurrent/ConcurrentHashMap/ToArray.java hangs after j.u.c updates
Description
The class java.util.concurrent.ForkJoinPool defines a number of system properties. The names of these properties are all good candidates to be wrapped with the recently new `{@systemProperty <prop-name>}` tag, which will cause these names to be placed in the main java doc Search index.
Comments
[~martin]That changeset has numerous code changes in it unrelated to the javadoc changes this bug deals with!
13-12-2018
Hmmm ... in retrospect it's obvious that the index could only point to one location, so having duplicate @systemProperty tags is a mistake. (One that could have been caught here by javadoc ... oh right, you mention that possibility in your comment ...) There's no obvious place to define java.util.secureRandomSeed. Maybe we let java.util.SplittableRandom win, just because it happens to match the package of java.util.secureRandomSeed. .... OK, done.
03-12-2018
The wrapping of the duplicate references to `java.util.secureRandomSeed` will cause problems down the road, since the intent is that the definition of a system property should be unique. This is part of the reason for creating the draft JEP for guidelines for documenting system properties. The long term plan is currently envisaged to be: * Verify use of `{@systemProperty}` is unique * Create a new index page for all system properties * Extend `@see`, `{@link}` to permit references to the definition of a system property
03-12-2018
https://cr.openjdk.java.net/~martin/webrevs/jdk/jsr166-integration/systemProperty/index.html
02-12-2018
It's probably not worth it to build the custom taglet, unless you find other users. We'll switch to using javadoc12 (linking to jdk11 api docs) consistently.
02-12-2018
{@systemProperty...} is an inline tag, and there is no way of using the existing -tag option to provide a spec for such tags. That could be an Enhancement. But, it would be easy to provide a custom taglet that would work on 11 that would have the effect you desire. Such a taglet would have to be provided via command-line options for -tagletpath and -taglet. Would that work for you?
01-12-2018
As usual, jsr166 tries to keep java sources compatible with jdk 11 and @systemProperty is only supported by jdk12+. We can live with that, but if there was an easy command line flag (e.g. -tag) to convert @systemProperty to @code for jdk < 12, we would use it.
01-12-2018