time: document that valid layouts are not valid Parse values

For #9346 #22135 explicitly state under layout constants
that they are not valid time values for Parse. Also add
examples of parsing valid RFC3339 values and the layout
to the example for time.Parse.

Fix capitalisation of time.Parse and Time.Format.

For #20869 include RFC3339 in the list of layouts that do
not accept all the time formats allowed by RFCs (lowercase z).
This does not fully address #20869.

Fixes #9346
Fixes #22135

Change-Id: Ia4c13e5745de583db5ef7d5b1688d7768bc42c1b
Reviewed-on: https://go-review.googlesource.com/74231
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/time/example_test.go

@@ -300,7 +300,7 @@ func ExampleTime_Format() {
 }
 
 func ExampleParse() {
-	// See the example for time.Format for a thorough description of how
+	// See the example for Time.Format for a thorough description of how
 	// to define the layout string to parse a time.Time value; Parse and
 	// Format use the same model to describe their input and output.
 
@@ -317,9 +317,25 @@ func ExampleParse() {
 	t, _ = time.Parse(shortForm, "2013-Feb-03")
 	fmt.Println(t)
 
+	// Valid layouts may not be a valid time value, due to format specifiers
+	// like _ for zero padding or Z for zone information.
+	// For example the RFC3339 layout 2006-01-02T15:04:05Z07:00
+	// contains both Z and a time zone offset in order to handle both valid options:
+	// 2006-01-02T15:04:05Z
+	// 2006-01-02T15:04:05+07:00
+	t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05Z")
+	fmt.Println(t)
+	t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05+07:00")
+	fmt.Println(t)
+	_, err := time.Parse(time.RFC3339, time.RFC3339)
+	fmt.Println("error", err) // Returns an error as the layout is not a valid time value
+
 	// Output:
 	// 2013-02-03 19:54:00 -0800 PST
 	// 2013-02-03 00:00:00 +0000 UTC
+	// 2006-01-02 15:04:05 +0000 UTC
+	// 2006-01-02 15:04:05 +0700 +0700
+	// error parsing time "2006-01-02T15:04:05Z07:00": extra text: 07:00
 }
 
 func ExampleParseInLocation() {

src/time/format.go

@@ -6,7 +6,7 @@ package time
 
 import "errors"
 
-// These are predefined layouts for use in Time.Format and Time.Parse.
+// These are predefined layouts for use in Time.Format and time.Parse.
 // The reference time used in the layouts is the specific time:
 //	Mon Jan 2 15:04:05 MST 2006
 // which is Unix time 1136239445. Since MST is GMT-0700,
@@ -18,6 +18,9 @@ import "errors"
 // reference time looks like so that the Format and Parse methods can apply
 // the same transformation to a general time value.
 //
+// Valid layouts may not be a valid time value for time.Parse, due to formats
+// like _ for zero padding or Z for zone information.
+//
 // Within the format string, an underscore _ represents a space that may be
 // replaced by a digit if the following number (a day) has two digits; for
 // compatibility with fixed-width Unix time formats.
@@ -49,7 +52,7 @@ import "errors"
 // time is echoed verbatim during Format and expected to appear verbatim
 // in the input to Parse.
 //
-// The executable example for time.Format demonstrates the working
+// The executable example for Time.Format demonstrates the working
 // of the layout string in detail and is a good reference.
 //
 // Note that the RFC822, RFC850, and RFC1123 formats should be applied
@@ -58,7 +61,7 @@ import "errors"
 // use of "GMT" in that case.
 // In general RFC1123Z should be used instead of RFC1123 for servers
 // that insist on that format, and RFC3339 should be preferred for new protocols.
-// RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
+// RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
 // when used with time.Parse they do not accept all the time formats
 // permitted by the RFCs.
 // The RFC3339Nano format removes trailing zeros from the seconds field
@@ -741,7 +744,7 @@ func skip(value, prefix string) (string, error) {
 // and convenient representations of the reference time. For more information
 // about the formats and the definition of the reference time, see the
 // documentation for ANSIC and the other constants defined by this package.
-// Also, the executable example for time.Format demonstrates the working
+// Also, the executable example for Time.Format demonstrates the working
 // of the layout string in detail and is a good reference.
 //
 // Elements omitted from the value are assumed to be zero or, when