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

New JavaDoc format is harder to read - Java 6 docs are more usable

    Details

    • Type: Enhancement
    • Status: Resolved
    • Priority: P3
    • Resolution: Duplicate
    • Affects Version/s: 7u25
    • Fix Version/s: None
    • Component/s: tools
    • Labels:

      Description

      A DESCRIPTION OF THE PROBLEM :
      in the 'Method Summary' section - the 'new' format takes two major steps in the wrong direction - when given a choice, I will use Java 6 documentation because it's easier to read.

      1) the type name should be right-justified in it's column to avoid massive whitespace between the type name and the method name. The alternating background colors help, but the large canyon is still problematic

      2) in the 'method and description' column, the Java 6 format (and all earlier formats I'm aware of) indented the description below the method name. In the new format, the lack of indentation (or, more to the point, the lack of out-dent for the method names) is a significant step backward for readability

      ===
      other sections are prettier, but not as well separated visually - so the net effect is reduced ease-of-use

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      (no documentation *content* changes required - this is a formatting issue)
      ACTUAL -
      (content is correct - but poorly formatted)

      URL OF FAULTY DOCUMENTATION :
      http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpatel Bhavesh Patel (Inactive)
                Reporter:
                rcalnan Roger Calnan
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: