time: Parse has no description of what errors it can generate

[weregamer]

go version go1.12.5 linux/amd64

This is a comment on the current godoc at https://golang.org/pkg/time/. This godoc does not offer any description of what is or is not an error in parsing.

Some possible errors are pretty obvious - out of range elements, for example (day of year 400, month 13, etc.)

And I do think it's reasonable to expect that you'll get an error if the string doesn't match up very well with the layout you gave (two-digit year instead of four, mismatched punctuation, etc.). But for most packages we seem to be more thorough in explaining border-case errors.

For example, what if the input string has some trailing stuff after the part to be parsed? One could argue that this is a mismatch of the format, and should be an error, or that this is something that should be let slide because you might be parsing just the beginning of a string. Again, I would interpolate the former and expect the caller to do some massaging, but it seems unwise to not be explicit.

[qbradq]

There are currently no tests of the time.Parse method that test error cases. Documenting the failure cases of the current implementation is in affect extending the API to include those failure cases. By my way of thinking that means tests would also need to be added to cover the now-documented failure cases.

I am happy to do any work needed for this. But I would like clarification on the above before I begin.

[dndungu]

I am giving this a try.

[erutherford]

Hey @dndungu, I wanted to check to see if you were still working on this. If you're not and you're ok with it, I'd like to take a look at it.

[seankhliao]

Without any exported errors to match against, I don't think it makes sense to document any specific errors.