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

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

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Duplicate
    • Icon: P3 P3
    • None
    • 7u25
    • tools

      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

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

              Created:
              Updated:
              Resolved: