Simplified std.datetime.package overview #6356

JackStouffer · 2018-03-27T17:02:07Z

Many people have remarked that std.datetime is confusing: https://github.com/wilzbach/state-of-d-2018/blob/master/12h:%20Which%20parts%20of%20Phobos%20(D%27s%20Standard%20Library)%2C%20if%20any%2C%20do%20you%20find%20difficult%20to%20work%20with%3F

This is the first step to improving that situation.

This PR:

Gives links to symbols based on usage in a clear table
Adds the most common usage of datetime in examples
Removes a large amount of text that is repeated elsewhere. I believe this text was either self-explanitory or gone over on each of the respective function docs

dlang-bot · 2018-03-27T17:02:11Z

Thanks for your pull request, @JackStouffer!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub fetch digger
dub run digger -- build "master + phobos#6356"

JackStouffer · 2018-03-27T17:03:42Z

This is just another step along the way to making std.datetime more accessible. I also want to add top level examples to all datetime modules to quickly introduce the concepts of the module.

wilzbach

Nice! I never liked this huge wall of text.
Waiting for @jmdavis's approval though.

wilzbach · 2018-03-27T17:32:38Z

std/datetime/package.d

+    import std.datetime.timezone : UTC;
+    import core.time : days;
+
+    auto st = SysTime(DateTime(2018, 1, 1, 12, 30, 10), UTC());


Maybe use an actual TimeZone here, s.t. it's non-trivial?

UTC is a TimeZone.

wilzbach · 2018-03-27T17:35:03Z

Haha ironically auto-tester is running in a spurious failure in std.datetime in this PR on FreeBSD:

timelimit: sending warning signal 15
gmake[1]: *** [posix.mak:380: unittest/std/datetime/systime.run] Error 143

https://auto-tester.puremagic.com/show-run.ghtml?projectid=1&runid=3094297&isPull=true

JackStouffer · 2018-03-28T15:16:28Z

What's up with MREF throwing out malformed HTML?

http://dtest.dlang.io/artifact/website-774b335033cedcb7eec8178408bfa3ad5ba2c011-56a6b22e12c72884486cc8bd4920b952/web/phobos-prerelease/std_datetime.html

wilzbach · 2018-03-28T15:30:04Z

std/datetime/package.d

+    This functionality is separated into the following modules
+
+    $(UL
+        $(LI $(MREF std, datetime, date))


You need to use _datetime here. While opt-out of automatic keyword highlighting is available since 2.079, it hasn't been applied to dlang.org yet:

https://dlang.org/changelog/2.079.0.html#fix18361

Let's turn the switch -> dlang/dlang.org#2307

jmdavis

I don't know. I can't say that I particularly like these changes. Turning some of the information into a table is definitely an improvement, but a lot of information is lost here. It does need to be rewritten on some level, with some of it being in the specific modules and some of it being here, but throwing it all out seems like a terrible idea to me. However, I can't really direct anyone on how to rewrite it. I'm just going to have to find the time to do it myself. Maybe it's better to let these changes through (with a few tweaks) and have the information here be butchered until I'm able to improve it, but I don't know.

jmdavis · 2018-03-29T06:45:16Z

std/datetime/package.d

-             $(LREF StopWatch))
-        $(LI Benchmarking functions.)
-        $(LI Various helper functions.)
+    Phobos provides the following functionality for time:


dates and times

This is referring to time the concept and not time on the clock.

jmdavis · 2018-03-29T06:48:16Z

std/datetime/package.d

+    $(TR
+        $(TD Intervals of Time)
+        $(TD
+            $(REF_ALTTEXT Interval, Interval, std, _datetime, interval)$(NBSP)


If you're trying to list the various types, even if you don't care about the range types in the module, there is also PosInfInterval and NegInfInterval.

jmdavis · 2018-03-29T06:50:37Z

std/datetime/package.d

+    import std.datetime.timezone : UTC;
+    import core.time : days;
+
+    auto st = SysTime(DateTime(2018, 1, 1, 12, 30, 10), UTC());


UTC is a TimeZone.

jmdavis · 2018-03-29T06:51:25Z

std/datetime/package.d

+
+    auto st = SysTime(DateTime(2018, 1, 1, 12, 30, 10), UTC());
+    assert(st.toISOExtString() == "2018-01-01T12:30:10Z");
+    st += 2.days;


I confess that I hate this syntax and would much prefer days(2), though some folks do seem to really like that syntax.

jmdavis · 2018-03-29T06:53:30Z

std/datetime/package.d

+        )
+    )
+    $(TR
+        $(TD Durations of Time)


I don't know about these. They're all in core.time, not std.datetime, though they're used quite heavily in std.datetime. So, on the one hand, it's kind of odd to list things, and on the other hand, it does make some sense. If they're going to be listed though, then there should also be a section for the monotonic time listing core.time.MonoTime.

JackStouffer · 2018-03-29T12:55:04Z

I don't think much information is lost. A lot of what's written here is covered in the documentation for the modules and for the types.

n8sh · 2018-03-30T15:38:44Z

I don't think much information is lost. A lot of what's written here is covered in the documentation for the modules and for the types.

The only thing that leaps out to me as needing module-level explanation is a table of accepted time unit strings. (For ease of learning units probably should have been an enumerated type rather than raw strings, but documentation is for what exists.)

JackStouffer · 2018-04-03T17:52:07Z

The only thing that leaps out to me as needing module-level explanation is a table of accepted time unit strings.

I think that would go on the individual module docs.

@jmdavis Ping.

wilzbach · 2018-04-04T10:51:32Z

std/datetime/package.d

+    $(TR
+        $(TD Points in Time)
+        $(TD
+            $(REF_ALTTEXT Date, Date, std, _datetime, date)$(NBSP)


Preventing auto-highlighting is no longer needed :)
see e.g. dlang/dlang.org#2307

wilzbach · 2018-04-04T10:53:14Z

std/datetime/package.d

+        $(LI $(MREF std, _datetime, timezone))
+        $(LI $(MREF std, _datetime, systime))
+        $(LI $(MREF std, _datetime, interval))
+        $(LI $(MREF std, _datetime, stopwatch))


Maybe add a short, one-line description of each of these packages, s.t. the user knows what the difference betwen date and systime is?

jmdavis · 2018-04-04T11:00:24Z

I don't think much information is lost. A lot of what's written here is covered in the documentation for the modules and for the types.

Some of the information that was here should be in the package documentation as part of an overview, and some if really just belongs in the modules. The result of these changes is that we pretty much just end up with a table listing the types and a distinct lack of any kind of explanation.

I guess that I'll let Seb merge this when his requested changes are done, but pretty the only way that I'm going to be happy with this is if I take the time to go over the module documentation for each module in std.datetime (including package.d) and rework it. In the interim, at least these changes get rid of the reference to std.datetime being a module, and the table cleans up what information is kept even if just about everything else is lost in the process. Unfortunately, I simply don't have the time to spend on reworking the docs right now. I guess that I'll try to tackle that during dconf.

JackStouffer added the Severity:Documentation label Mar 27, 2018

JackStouffer requested a review from wilzbach March 27, 2018 17:02

JackStouffer requested a review from jmdavis as a code owner March 27, 2018 17:02

JackStouffer force-pushed the datetime-docs branch from ba690ab to aa9df33 Compare March 27, 2018 17:05

wilzbach approved these changes Mar 27, 2018

View reviewed changes

wilzbach assigned jmdavis Mar 27, 2018

JackStouffer force-pushed the datetime-docs branch from aa9df33 to 6901b47 Compare March 28, 2018 12:46

wilzbach reviewed Mar 28, 2018

View reviewed changes

wilzbach mentioned this pull request Mar 28, 2018

Start to opt-out of Ddoc's automatic keyword highlighting dlang/dlang.org#2307

Merged

JackStouffer force-pushed the datetime-docs branch 2 times, most recently from 58d4f7d to 905a6b9 Compare March 28, 2018 16:09

jmdavis requested changes Mar 29, 2018

View reviewed changes

JackStouffer force-pushed the datetime-docs branch from 905a6b9 to 0758786 Compare March 29, 2018 12:55

JackStouffer force-pushed the datetime-docs branch from 0758786 to b814453 Compare April 3, 2018 17:49

wilzbach reviewed Apr 4, 2018

View reviewed changes

jmdavis approved these changes Apr 4, 2018

View reviewed changes

Simplified std.datetime.package overview

a737f62

JackStouffer force-pushed the datetime-docs branch from b814453 to a737f62 Compare April 4, 2018 13:24

JackStouffer added the Merge:auto-merge label Apr 4, 2018

dlang-bot merged commit 0d45880 into dlang:master Apr 5, 2018

JackStouffer deleted the datetime-docs branch April 5, 2018 11:07

Uh oh!

Simplified std.datetime.package overview #6356

Simplified std.datetime.package overview #6356

Uh oh!

Conversation

JackStouffer commented Mar 27, 2018

Uh oh!

dlang-bot commented Mar 27, 2018

Bugzilla references

Testing this PR locally

Uh oh!

JackStouffer commented Mar 27, 2018

Uh oh!

wilzbach left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wilzbach commented Mar 27, 2018

Uh oh!

JackStouffer commented Mar 28, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmdavis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JackStouffer commented Mar 29, 2018

Uh oh!

n8sh commented Mar 30, 2018

Uh oh!

JackStouffer commented Apr 3, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmdavis commented Apr 4, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants