-
Enhancement
-
Resolution: Duplicate
-
P3
-
None
-
7u25
-
windows_7
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
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
- duplicates
-
JDK-8016549 jdk7 javadocs are hard to read
-
- Resolved
-