time: improve Documentation for Parse for zone offsets

[abraithwaite]

What version of Go are you using (go version)?

$ go version
go version go1.11.4 darwin/amd64

Does this issue reproduce with the latest release?

Yes. Checked master and docs have not changed in tip either.

What did you do?

https://play.golang.org/p/bvmvzOstarf

Edit: the zone in this should be PST, but the result is the same ^

What did you expect to see?

I expected to see the timezone offset to be set accordingly.

What did you see instead?

The timezone numeric offset was not set, despite Zone() returning a text zone.

Proposal

For those unfamiliar with timezones, we are unaware that timezone abbreviations are ambiguous. The docs make it clear that in order for those textual time zones to be parsed and set an offset, it must be parsed in the context of a location. However, it's not immediately clear that you will have a problem trying to parse dates with a timezone abbreviation.

I propose adding a simple line: "Timezone abbreviations like "MST" are ambiguous, therefore..." to the docs.

go/src/time/format.go

Lines 764 to 772 in 84066f1

	// When parsing a time with a zone abbreviation like MST, if the zone abbreviation
	// has a defined offset in the current location, then that offset is used.
	// The zone abbreviation "UTC" is recognized as UTC regardless of location.
	// If the zone abbreviation is unknown, Parse records the time as being
	// in a fabricated location with the given zone abbreviation and a zero offset.
	// This choice means that such a time can be parsed and reformatted with the
	// same layout losslessly, but the exact instant used in the representation will
	// differ by the actual zone offset. To avoid such problems, prefer time layouts
	// that use a numeric zone offset, or use ParseInLocation.

We discovered this during a migration from Javascript, which does set a numeric offset even in the absence of a predefined location (servers location is UTC, but still parses PDT as -07:00)

[agnivade]

/cc @robpike

[seankhliao]

looks like this was added.