IMO, if we change it, we should change the ";" into ", while". I think natural language is better than formatted bullet points.
On Fri, May 28, 2021 at 1:45 PM NieomylnieJa <matihaw...@gmail.com> wrote: > Thank you for your responses. While I'm convinced that `ParseInLocation` > works as intended and I do get that UTC is an unambiguous zone, the only > thing I still have problem with is with the way this is phrased in the > docs. I had 5 of my colleagues looking at it and none of us has had clarity > as to how to interpret these lines: > > // First, in the absence of time zone information, Parse interprets a time > as UTC; > // ParseInLocation interprets the time as in the given location. > > All I'm saying is that it sounds like `Parse` interprets time as UTC in > the absence of TZ information, while `ParseInLocation` will interpret it in > the given location period (disregarding the TZ if provided). > As the Merriam-Webster reference to the semicolon usage also leaves space > for the interpretation the docs should avoid semantically ambiguous lines > like those in my opinion. What do you think? > > This would be clearer to me (although I've got no idea what style rules, > If any are required for the docs): > // First, in the absence of time zone information: > // - Parse interprets a time as UTC > // - ParseInLocation interprets the time as in the given location > piątek, 28 maja 2021 o 12:44:26 UTC+2 Ian Davis napisał(a): > >> On Fri, 28 May 2021, at 11:32 AM, NieomylnieJa wrote: >> >> But the docs state something different: >> >> // ParseInLocation is like Parse but differs in two important ways. >> // First, in the absence of time zone information, Parse interprets a >> time as UTC; >> // ParseInLocation interprets the time as in the given location. >> // Second, when given a zone offset or abbreviation, Parse tries to match >> it >> // against the Local location; ParseInLocation uses the given location. >> >> The docs explicitly state that: "*ParseInLocation interprets the time as >> in the given location*". This behavior in conjunction with the docs were >> confusing to me and a number of my coworkers, shouldn't they be updated? >> It's not quiet straightforward that this line "*First, in the absence of >> time zone information (...)*" refers to "ParseInLocation" too, the >> semicolon doesn't help either, as the interpretation may differ: >> Merriam-Webster >> reference >> <https://www.merriam-webster.com/words-at-play/a-guide-to-using-semicolons> >> >> >> I think those docs are clear: >> >> (1) in the absence of time zone information Parse assumes UTC but >> ParseInLocation uses the location's timezone. >> >> (2) when a timezone is given Parse uses the Local (current) location to >> resolve the name of the timezone, but ParseInLocation uses the location >> passed. This allows local names for timezones to be resolved correctly. For >> example CST has several different possible meanings. >> >> However Z is an unambiguous timezone - it always means UTC. So your >> example will use UTC for the timezone. >> >> Ian >> >> >> -- > You received this message because you are subscribed to the Google Groups > "golang-nuts" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to golang-nuts+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/golang-nuts/05d761f3-234e-4c24-9073-b3b0a9b850f9n%40googlegroups.com > <https://groups.google.com/d/msgid/golang-nuts/05d761f3-234e-4c24-9073-b3b0a9b850f9n%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- You received this message because you are subscribed to the Google Groups "golang-nuts" group. To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/CAEkBMfGys7XizD6MjUM6bQNzS4TnWM7m8M07dgTksFeKtfp8Wg%40mail.gmail.com.
