-
Notifications
You must be signed in to change notification settings - Fork 527
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for DateTime
#1040
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is great!
Feedback is recommended but not required.
Thank you for the good suggestions! I will add new commits to address review comments, and can squash them before later. |
f774318
to
52cbb17
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's split this in one PR per type. Please squash any review feedback into the relevant commits.
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should mention both the operator and the checked methods here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.
DateTime
and TimeZone
DateTime
1bde437
to
11723f5
Compare
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 |
94ad56e
to
00e5e7f
Compare
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.