time: improve the explanation of the working of Format and Parse

Change the term 'standard time', which already means something,
to 'reference time', and add a couple of sentences and clarifications.

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/8799047

diff --git a/src/pkg/time/example_test.go b/src/pkg/time/example_test.go
index 8928caababaaaaaad353b99f426444befcfb3787..cfa5b38c5f13e86fb8b902b77368935adacd3124 100644 (file)
--- a/src/pkg/time/example_test.go
+++ b/src/pkg/time/example_test.go
@@ -58,20 +58,25 @@ func ExampleDate() {
 }
 
 func ExampleTime_Format() {
-       const format = "Jan 2, 2006 at 3:04pm (MST)"
+       // layout shows by example how the reference time should be represented.
+       const layout = "Jan 2, 2006 at 3:04pm (MST)"
        t := time.Date(2009, time.November, 10, 15, 0, 0, 0, time.Local)
-       fmt.Println(t.Format(format))
-       fmt.Println(t.UTC().Format(format))
+       fmt.Println(t.Format(layout))
+       fmt.Println(t.UTC().Format(layout))
        // Output:
        // Nov 10, 2009 at 3:00pm (PST)
        // Nov 10, 2009 at 11:00pm (UTC)
 }
 
 func ExampleParse() {
+       // longForm shows by example how the reference time would be represented in
+       // the desired layout.
        const longForm = "Jan 2, 2006 at 3:04pm (MST)"
        t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (PST)")
        fmt.Println(t)
 
+       // shortForm is another way the reference time would be represented
+       // in the desired layout; it has no time zone present.
        // Note: without explicit zone, returns time in UTC.
        const shortForm = "2006-Jan-02"
        t, _ = time.Parse(shortForm, "2013-Feb-03")

diff --git a/src/pkg/time/format.go b/src/pkg/time/format.go
index 817c79a80131667f8d497d8a9430ad20eecbdb94..f18ea62f6016f6ca6793037b2d743d483c1df588 100644 (file)
--- a/src/pkg/time/format.go
+++ b/src/pkg/time/format.go
@@ -6,15 +6,17 @@ package time
 
 import "errors"
 
-// These are predefined layouts for use in Time.Format.
-// The standard time used in the layouts is:
+// These are predefined layouts for use in Time.Format and Time.Parse.
+// The reference time used in the layouts is:
 //     Mon Jan 2 15:04:05 MST 2006
 // which is Unix time 1136239445. Since MST is GMT-0700,
-// the standard time can be thought of as
+// the reference time can be thought of as
 //     01/02 03:04:05PM '06 -0700
-// To define your own format, write down what the standard time would look
+// To define your own format, write down what the reference time would look
 // like formatted your way; see the values of constants like ANSIC,
-// StampMicro or Kitchen for examples.
+// StampMicro or Kitchen for examples. The model is to demonstrate what the
+// reference time looks like so that the Format and Parse methods can apply
+// the same transformation to a general time value.
 //
 // 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
@@ -367,13 +369,16 @@ func (t Time) String() string {
 }
 
 // Format returns a textual representation of the time value formatted
-// according to layout.  The layout defines the format by showing the
-// representation of the standard time,
+// according to layout, which defines the format by showing how the reference
+// time,
 //     Mon Jan 2 15:04:05 -0700 MST 2006
-// which is then used to describe the time to be formatted. Predefined
-// layouts ANSIC, UnixDate, RFC3339 and others describe standard
-// representations. For more information about the formats and the
-// definition of the standard time, see the documentation for ANSIC.
+// would be displayed if it were the value; it serves as an example of the
+// desired output. The same display rules will then be aplied to the time
+// value.
+// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
+// 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.
 func (t Time) Format(layout string) string {
        var (
                name, offset, abs = t.locabs()
@@ -627,13 +632,15 @@ func skip(value, prefix string) (string, error) {
 }
 
 // Parse parses a formatted string and returns the time value it represents.
-// The layout defines the format by showing the representation of the
-// standard time,
+// The layout  defines the format by showing how the reference time,
 //     Mon Jan 2 15:04:05 -0700 MST 2006
-// which is then used to describe the string to be parsed. Predefined layouts
-// ANSIC, UnixDate, RFC3339 and others describe standard representations. For
-// more information about the formats and the definition of the standard
-// time, see the documentation for ANSIC.
+// would be interepreted if it were the value; it serves as an example of
+// the input format. The same interpretation will then be made to the
+// input string.
+// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
+// 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.
 //
 // Elements omitted from the value are assumed to be zero or, when
 // zero is impossible, one, so parsing "3:04pm" returns the time