[Issue 18398] New: std.datetime.stopwatch documented examples could be better

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=18398

          Issue ID: 18398
           Summary: std.datetime.stopwatch documented examples could be
                    better
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: minor
          Priority: P1
         Component: phobos
          Assignee: nobody at puremagic.com
          Reporter: n8sh.secondary at hotmail.com

Someone using `std.datetime.stopwatch` probably wants to use it to obtain a
time in milliseconds or some other unit of time but none of the example code on
the page involves converting a core.time.Duration. This makes the examples less
helpful to a newcomer than they could be.

Proposed addition:

```d
    /// Measure a time in milliseconds, microseconds, or nanoseconds
    @safe nothrow @nogc unittest
    {
        auto sw = StopWatch(AutoStart.no);
        sw.start();
        // ... Insert operations to be timed here ...
        sw.stop();

        long msecs = sw.peek().total!"msecs";
        long usecs = sw.peek().total!"usecs";
        long nsecs = sw.peek().total!"nsecs";

        assert(usecs >= msecs * 1000);
        assert(nsecs >= usecs * 1000);
    }
```

--