Documentation for DateTime
#1040
Conversation
|
Thank you for the good suggestions! I will add new commits to address review comments, and can squash them before later. |
pitdicker
force-pushed
the
datetime_doc
branch
6 times, most recently
from
f774318
to
52cbb17
Compare
| @@ -79,11 +79,141 @@ pub enum SecondsFormat { | |||
| __NonExhaustive, | |||
| } | |||
|
|
|||
| /// ISO 8601 combined date and time with time zone. | |||
| /// `DateTime` is the preferred type for working with real-world timestamps. It contains all the | |||
| /// information needed to exactly specify a point in time, and to do calculations on it: a date, | |||
There was a problem hiding this comment.
I'm not sure it is correct to say that DateTime "contains" a "timezone". It contains the offset, but not the timezone itself. Maybe that can be worded differently?
There was a problem hiding this comment.
I am not sure how to word it better. Changed it to "and associated time zone" for now. But the paragraph below explains that the time zone is tracked by the type system.
There was a problem hiding this comment.
As I explained, my beef is with the word "contains". The next paragraph goes into a lot more detail, so I think we should get this first, high-level description right.
There was a problem hiding this comment.
How about "It carries all the information needed to exactly specify a point in time"?
src/datetime/mod.rs
Outdated
| /// - [`Sub<DateTime>`] to get a [`Duration`](struct.Duration.html) with the difference between two | ||
| /// datetimes. | ||
| /// - [`Add<Duration>`] to add a [`Duration`](struct.Duration.html) of an absolute number of | ||
| /// - [`signed_duration_since`](#method.signed_duration_since) to get a [`Duration`]( |
There was a problem hiding this comment.
I think we should mention both the operator and the checked methods here.
There was a problem hiding this comment.
The line below says "The same functionality is also available with implementations of Add and Sub."
I initially made those more prominent, but they are not a great idea to use because they can panic in pretty common scenarios.
To make them a bit more visible I added an example of working with DateTimes.
pitdicker
changed the title
DateTime and TimeZoneDateTime
pitdicker
force-pushed
the
datetime_doc
branch
6 times, most recently
from
1bde437
to
11723f5
Compare
pitdicker
force-pushed
the
datetime_doc
branch
from
11723f5
to
94ad56e
Compare
|
Finally updated. Sorry to let this linger for 3+ months. |
Codecov Report
@@ Coverage Diff @@
## 0.4.x #1040 +/- ##
==========================================
- Coverage 91.50% 91.45% -0.06%
==========================================
Files 38 38
Lines 17314 17341 +27
==========================================
+ Hits 15844 15860 +16
- Misses 1470 1481 +11
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
pitdicker
force-pushed
the
datetime_doc
branch
from
94ad56e
to
00e5e7f
Compare
pitdicker
force-pushed
the
datetime_doc
branch
from
00e5e7f
to
d6b8bb4
Compare
If the general direction of this documentation seems useful, I can write it for more types.
My idea is to give a tour of the available methods on a type, similar to
std::Option.Useful examples could also be a plus, but this is just a start.