time: mention reference date used for formatting in time.Parse

[chriseyre2000]

As of go1.17.1

This is a documentation issue so environment and recreation issues are irrelevent.

The documentation for the time.Parse fails to mention the "magical reference date"
(https://programming.guide/go/format-parse-string-time-date-example.html)

This makes working with date parsing much harder than it needs to be.

[ALTree]

It does say in the 2nd sentence of the function's doc:

See the documentation for the constant called Layout to see how to represent the format.

Of course is not advisable to duplicate the information in the doc of every function that uses the format.

[chriseyre2000]

Hiding a key documentation point in a comment in an example function is close to the HHGTG: https://www.goodreads.com/quotes/40705-but-the-plans-were-on-display-on-display-i-eventually

I am not asking it to be copied everywhere, merely to be added to the documentation of the Parse function.

[ALTree]

Hiding a key documentation point in a comment in an example function

?

I'm referring to the section at the top of the package: https://pkg.go.dev/time#pkg-constants. It's hard to see how anyone scrolling through the documentation of time could miss the huge section about the layout string right at the beginning.

The fixed layout string is used in Parse and in Format and in ParseInLocation and in AppendFormat. We'd need to replicate that big explanation several times.

[chriseyre2000]

The explanation in https://pkg.go.dev/time@go1.17.1#Time.Format example is great.
However it is by default collapsed (and even when not collapsed is shown in a low contrast colour combination).

Now I know what the layout string is it makes sense. Without that information it is very confusing.

[seankhliao]

I don't think there's anything to do here. If you read the signature for time.Parse, the first paragraph will redirect you to Layout, and if you searched the entire doc for reference time, the first instance is also for Layout.

The examples are that that, examples, and not suited for the function doc itself. Note that time.Parse also has an example (which will point you to time.Format for a longer explanation).

[mknyszek]

CC @rsc via https://dev.golang.org/owners

[gopherbot]

Timed out in state WaitingForInfo. Closing.

(I am just a bot, though. Please speak up if this is a mistake or you have the requested information.)

[jeroendee]

👍 I'm learning Go, and this magical ref. date was very weird to me (compared to C# format string patterns). I really couldn't get why my chosen format pattern didn't work. Only after googling towards the site mentioned in the opening comment, I came to understand you have to use this specific date in order to let your composed format work. This is after reading:

• the package time info
• https://gobyexample.com/time-formatting-parsing
• https://yourbasic.org/golang/format-parse-string-time-date-example/ (even mentions: "This date is easier to remember when written as 01/02 03:04:05PM ‘06 -0700")

We (at least I) probably look for the pattern to use first, only to realise that the pattern + the exact ref. values are needed.

Indeed in all the examples from the sites mentioned in the above, they use the same ref. date. But again it's not very clear that is THE ref date one should use.