Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8177417

Constructor Summary readability problems in jdk9 javadoc

    XMLWordPrintable

    Details

    • Subcomponent:
    • Resolved In Build:
      b165
    • Verification:
      Verified

      Backports

        Description

        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.

          Attachments

            Issue Links

              Activity

                People

                Assignee:
                bpatel Bhavesh Patel (Inactive)
                Reporter:
                martin Martin Buchholz
                Votes:
                0 Vote for this issue
                Watchers:
                6 Start watching this issue

                  Dates

                  Created:
                  Updated:
                  Resolved: