Update ZonedDateTime constructor to clarify behaviour when from_utc=false

[iamed2]

I got caught by this and almost assumed something incorrect about the downstream CloudWatchLogs.jl library. The "instead of in local time" clause implied to me that when from_utc=false the DateTime would be converted from localzone() into the specified TimeZone, but that is not the case.

[codecov-commenter]

Codecov Report

Merging #367 (e881857) into master (e0a66bf) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #367   +/-   ##
=======================================
  Coverage   93.75%   93.75%           
=======================================
  Files          31       31           
  Lines        1553     1553           
=======================================
  Hits         1456     1456           
  Misses         97       97           

Impacted Files	Coverage Δ
src/types/zoneddatetime.jl	96.15% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e0a66bf...e881857. Read the comment docs.

[omus]

The "instead of in local time" clause implied to me that when from_utc=false the DateTime would be converted from localzone() into the specified TimeZone, but that is not the case.

Definitely seems to be a perspective issue. The original documentation was written with the idea that it was known that internally a UTC datetime is stored. The primary reason from_utc is for performance reasons so using the term "convert" could been interpreted that using from_utc=true is slower.

[omus]

Better?

Suggested change

	keyword is true the given `DateTime` is assumed to be in UTC and is converted to the specified
	`TimeZone`. When `from_utc` is false the given `DateTime` is assumed to already be in the
	specified `TimeZone`. Note that when `from_utc` is true the given `DateTime` will always exist
	and is never ambiguous.
	keyword is `true` the given `DateTime` is declared to be in UTC but will be displayed in the specified
	`TimeZone`. When `from_utc` is `false` the given `DateTime` is declared to be in local time (the
	specified `TimeZone`). Note that when `from_utc` is `true` the provided UTC `DateTime` will always exist
	and is never ambiguous.

[iamed2]

I think "will be displayed" leaks the abstraction; to the user, they don't need to know that the underlying storage is in UTC. I can see why you would want to avoid "converted" though. I'm struggling to come up with good wording.

I think the phrase "local time" should be avoided to avoid confusion with localzone()/the OS time zone.

[omus]

I think "will be displayed" leaks the abstraction; to the user, they don't need to know that the underlying storage is in UTC. I can see why you would want to avoid "converted" though. I'm struggling to come up with good wording.

I'm definitely up for suggestions. I think this part of the documentation has been hard to get right.

I think the phrase "local time" should be avoided to avoid confusion with localzone()/the OS time zone.

The phrase "local time" is something the IANA documentation uses and isn't quite perfect as really it just refers to only the time component. Maybe "local timestamp" or "local DateTime" is an improvement.

I suspect we'll have to iterate on this a little bit. Thank you for opening the PR :)