On 19.11.2017 20:29, Jon Degenhardt wrote:
...
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.
This is exactly how I think about this. I'd additionally recommend to
keep supporting something like "to". It's nicer to read than something
like total!"hnsecs"/1e7.
