TickDuration deprecation

[Jon Degenhardt]

On Sunday, 19 November 2017 at 16:02:34 UTC, Jonathan M Davis 
wrote:
> On Sunday, November 19, 2017 15:01:50 Rumbu via Digitalmars-d 
> wrote:
>> On Saturday, 18 November 2017 at 22:46:20 UTC, Jon Degenhardt

> Was the documentation on Duration not informative enough, or 
> did you have trouble finding it from the documentation for the 
> benchmarking functions, or something else? Simply converting a 
> Duration to a string gives you what I would have thought would 
> have been plenty human readable (though obviously not 
> necessarily what you want in all cases), and it's split and 
> total functions should make it straightforward to put the 
> result in some other format if that's what you want. Was the 
> documentation on those not enough?

1) Finding the documentation for Duration from the documentation 
of std.datetime.stopwatch is not quick enough. There is only one 
link from the page, and it's near the bottom, with the benchmark 
function (which is rarely what I need). Also, aside from the link 
at the bottom of the page, no mention of what module it is in.

2) The stopwatch page doesn't describe a Duration, and it also 
refers to core.time.MonoTime, plus a discussion that the 
"precision of StopWatch differs from system to system. And 
references to the depreciated TickDuration

Before one can do anything, one has to parse through all this 
material. It's all necessary material for tasks requiring very 
high accuracy. However, if what is being timed is inherently 
precise only to hundreds or tens of milliseconds, then this is 
way more investigation than needs to be done for the task at hand.

3) hecto-nanoseconds is not an especially common unit of measure.

4) Even from the Duration documentation, there aren't many 
examples of conversion to other standard units of measure. The 
only one I see is converting 12 days to hecto-nanoseconds, which 
isn't helpful as an example.

5) The built in conversion to string is one I've never found 
useful. Generally, I'm putting a set a values in a table, perhaps 
a large table. The output shown is not amenable to this. And yes, 
it often needs to be both human and machine readable. For 
example, I may read the table into R and plot the values.

Some recommendations:

a) Put a link to the Duration documentation in StopWatch page.

b) Put examples in the StopWatch and Duration sections that 
explicitly show how to convert to usecs, milliseconds, and 
perhaps seconds in floating point formats. Show this in the 
context of printing them.

c) Try to clean up some of the language describing the backward 
compatibility vs the newer stuff. It's a bit intertwined. The 
language doesn't have to explain the depreciation or justify it, 
at least not mixed with the description of the new facilities.

d) Be more explicit in the documentation about tradeoffs of 
integer precision used in Duration and floating point accuracy. 
That Duration supports this high accuracy without loss of 
precision in the face of mathematical operations is a real value, 
one worth calling out. However, it's also the case that this high 
mathematical precision is not required for many timing use cases, 
especially in the printing, but even calculations.

Making this distinction puts the stopwatch facilities more in the 
position of being an enabler of good end-user choices and less 
trying to prevent end-user mistakes. The reality is, that the 
accuracy needs are only known in the context of the timing 
measurements being done. The library code does not have enough 
information to know. However, providing the user with the 
information to make good choices about accuracy representation is 
a real benefit.