Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
chriseyre2000 opened this issue Oct 4, 2021 · 8 comments
Closed

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

chriseyre2000 opened this issue Oct 4, 2021 · 8 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided.
Milestone

Comments

@chriseyre2000
Copy link

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
Copy link
Member

ALTree commented Oct 4, 2021

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
Copy link
Author

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
Copy link
Member

ALTree commented Oct 4, 2021

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
Copy link
Author

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
Copy link
Member

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 mknyszek changed the title Mention the magical reference date in time.Parse time: mention reference date used for formatting in time.Parse Oct 4, 2021
@mknyszek mknyszek added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Oct 4, 2021
@mknyszek mknyszek added this to the Backlog milestone Oct 4, 2021
@mknyszek
Copy link
Contributor

mknyszek commented Oct 4, 2021

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

@ianlancetaylor ianlancetaylor added the WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided. label Oct 5, 2021
@gopherbot
Copy link

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
Copy link

👍 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:

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.

@golang golang locked as resolved and limited conversation to collaborators Jan 11, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. WaitingForInfo Issue is not actionable because of missing required information, which needs to be provided.
Projects
None yet
Development

No branches or pull requests

7 participants