JDK-8062796 : java.time.format.DateTimeFormatter error in API doc example
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.time
  • Affected Version: 8u25
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: windows_7
  • CPU: x86_64
  • Submitted: 2014-10-25
  • Updated: 2015-09-29
  • Resolved: 2015-06-17
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 8 JDK 9
8u60 b22Fixed 9Fixed
Related Reports
Duplicate :  
Duplicate :  
Duplicate :  
Description
A DESCRIPTION OF THE PROBLEM :
The description for the DateTimeFormatter provides two Java snippets which have several issues. 

These are those two examples:

First example:

  String text = date.toString(formatter);
  LocalDate date = LocalDate.parse(text, formatter);

Second example:

  DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
  String text = date.toString(formatter);
  LocalDate date = LocalDate.parse(text, formatter);

The Issues:
[1] There is no need to provide both examples in the description; the second is sufficient.
[2] Both examples are invalid Java.
[3] Both examples reference a variable name "date" before it is declared.
[4] Both examples pass method "toString()" a "DateTimeFormatter" argument, but no such method exists in the JDK. Presumably the calls should be to method format() rather than toString().







EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
A clearer and valid example for the DateTimeFormatter documentation might be:

            LocalDate date1 = LocalDate.of(2014, 10, 25);
            System.out.println("date1: " + date1.toString());
            DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
            String text = date1.format(formatter);
            LocalDate date2 = LocalDate.parse(text, formatter);
            System.out.println("date2: " + date2.toString());

ACTUAL -
The following erroneous text appears in the DateTimeFormatter documentation:

  String text = date.toString(formatter);
  LocalDate date = LocalDate.parse(text, formatter);

.....

  DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
  String text = date.toString(formatter);
  LocalDate date = LocalDate.parse(text, formatter);


URL OF FAULTY DOCUMENTATION :
http://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html


Comments
Actually this is a suggestion to improve or simplify examples provided in this document: http://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html
04-11-2014