-
Bug
-
Resolution: Fixed
-
P2
-
9
-
b165
-
Verified
Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
---|---|---|---|---|---|---|
JDK-8178749 | 10 | Bhavesh Patel | P2 | Resolved | Fixed | b05 |
I was comparing jdk9 and jdk8 javadoc for ThreadPoolExecutor, and noticed a serious readability regression in the "Constructor Summary" section.
https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html#constructor.summary
http://download.java.net/java/jdk9/docs/api/java/util/concurrent/ThreadPoolExecutor.html#constructor.summary
At first I thought that the first sentence description was simply missing in jdk9, but in fact this class has constructors with very long parameter lists and the description is invisibly scrunched up at the right (must scroll to see). I think the approach in jdk8, where the first sentence description begins at the left margin, was much more readable. But even if I can't persuade you to change that and you decide to stick with the Description in a separate column, then you should break long constructor parameter lines as in ThreadPoolExecutor as you already appear to do with Method Summary, that is, apply the same line breaking algorithm to Constructor Summary signatures as you do with Method Summary signatures.
Since this is a jdk9 regression, consider fixing even this late in jdk9 development.
https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html#constructor.summary
http://download.java.net/java/jdk9/docs/api/java/util/concurrent/ThreadPoolExecutor.html#constructor.summary
At first I thought that the first sentence description was simply missing in jdk9, but in fact this class has constructors with very long parameter lists and the description is invisibly scrunched up at the right (must scroll to see). I think the approach in jdk8, where the first sentence description begins at the left margin, was much more readable. But even if I can't persuade you to change that and you decide to stick with the Description in a separate column, then you should break long constructor parameter lines as in ThreadPoolExecutor as you already appear to do with Method Summary, that is, apply the same line breaking algorithm to Constructor Summary signatures as you do with Method Summary signatures.
Since this is a jdk9 regression, consider fixing even this late in jdk9 development.
- backported by
-
JDK-8178749 Constructor Summary readability problems in jdk9 javadoc
-
- Resolved
-