Documentation update for Stopwatch
Added example for Stopwatch
Closes https://github.com/dart-lang/sdk/pull/47784
https://github.com/dart-lang/sdk/pull/47784
GitOrigin-RevId: 51fd1a9567090f22b42f59114330b3ce1f1e7a10
Change-Id: I6a497b6b9cf7ab9c120572b6bfd7a551a2016f59
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/221402
Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
diff --git a/sdk/lib/core/stopwatch.dart b/sdk/lib/core/stopwatch.dart
index 45da67e..959fcbe 100644
--- a/sdk/lib/core/stopwatch.dart
+++ b/sdk/lib/core/stopwatch.dart
@@ -4,7 +4,47 @@
part of dart.core;
-/// A simple stopwatch interface to measure elapsed time.
+/// A stopwatch which measures time while it's running.
+///
+/// A stopwatch is either running or stopped.
+/// It measures the elapsed time that passes while the stopwatch is running.
+///
+/// When a stopwatch is initially created, it is stopped and has measured no
+/// elapsed time.
+///
+/// The elapsed time can be accessed in various formats using
+/// [elapsed], [elapsedMilliseconds], [elapsedMicroseconds] or [elapsedTicks].
+///
+/// The stopwatch is started by calling [start].
+///
+/// Example:
+/// ```dart
+/// final stopwatch = Stopwatch();
+/// print(stopwatch.elapsedMilliseconds); // 0
+/// print(stopwatch.isRunning); // false
+/// stopwatch.start();
+/// print(stopwatch.isRunning); // true
+/// ```
+/// To stop or pause the stopwatch, use [stop].
+/// Use [start] to continue again when only pausing temporarily.
+/// ```
+/// stopwatch.stop();
+/// print(stopwatch.isRunning); // false
+/// Duration elapsed = stopwatch.elapsed;
+/// await Future.delayed(const Duration(seconds: 1));
+/// assert(stopwatch.elapsed == elapsed); // No measured time elapsed.
+/// stopwatch.start(); // Continue measuring.
+/// ```
+/// The [reset] method sets the elapsed time back to zero.
+/// It can be called whether the stopwatch is running or not,
+/// and doesn't change whether it's running.
+/// ```
+/// // Do some work.
+/// stopwatch.stop();
+/// print(stopwatch.elapsedMilliseconds); // Likely > 0.
+/// stopwatch.reset();
+/// print(stopwatch.elapsedMilliseconds); // 0
+/// ```
class Stopwatch {
/// Cached frequency of the system in Hz (ticks per second).
///
@@ -22,7 +62,7 @@
/// The following example shows how to start a [Stopwatch]
/// immediately after allocation.
/// ```dart
- /// var stopwatch = Stopwatch()..start();
+ /// final stopwatch = Stopwatch()..start();
/// ```
Stopwatch() {
_frequency; // Ensures initialization before using any method.
@@ -33,7 +73,7 @@
/// Starts the [Stopwatch].
///
- /// The [elapsed] count is increasing monotonically. If the [Stopwatch] has
+ /// The [elapsed] count increases monotonically. If the [Stopwatch] has
/// been stopped, then calling start again restarts it without resetting the
/// [elapsed] count.
///
