docs: "portable" values are always in UTC, right?

[pnkfelix]

When I was hacking up some code to print the actual date/time for a timestamp reported by this library, I was briefly flummoxed when it didn't match the results I saw from ls.

Then I eventually realized that ls was giving me times in my current locale, while this library always produces times relative to UTC.

This is unsurprising; this crate is after all just a thin veneer over utimes (at least on Unix), so the time zone handling is just going to be inherited from whatever the implementation of utimes does.

But: maybe the docs should explicitly note this, at least for fn seconds_relative_to_1970 and fn from_seconds_since_1970.

Just adding "(UTC)" to the description of the epoch would suffice, probably.

• Looking at the docs now, it doesn't even say "00:00:00" (aka midnight); it just says January 1, 1970. Heh.
• So maybe the full string "(more specifically, the Epoch: 1970-01-01 00:00:00 +0000 (UTC))" should be written after the occurrences of "January 1, 1970" in the docs.

[alexcrichton]

Makes sense to me!

Although I'm not sure if this is UTC 100% of the time, I'd have to check the documentation of the relevant syscalls here to see what they return...