document the stopwatch plugin

plugins/history.rst

@@ -1,7 +1,8 @@
 History Plugin
 ==============
 
-The ``HistoryPlugin`` notifies a Http\Client\Plugin\Journal of all successful and failed calls::
+The ``HistoryPlugin`` notifies a ``Http\Client\Plugin\Journal`` of all
+successful and failed calls::
 
     use Http\Discovery\HttpClientDiscovery;
     use Http\Client\Plugin\PluginClient;
@@ -15,8 +16,8 @@ The ``HistoryPlugin`` notifies a Http\Client\Plugin\Journal of all successful an
     );
 
 
-As an example, HttplugBundle uses this plugin to collect responses or exceptions associated with
-requests for the debug toolbar
+As an example, HttplugBundle uses this plugin to collect responses and exceptions associated with
+requests for the debug toolbar.
 
-This plugin only collect data after resolution. For logging purposes it's best to use the `LoggerPlugin` which logs
-as soon as possible.
+This plugin only collects data after resolution. For logging purposes, it is recommended to use
+the :doc:`LoggerPlugin <logger>` instead, which logs events as they occur.

plugins/stopwatch.rst

@@ -1,4 +1,34 @@
 Stopwatch Plugin
 ================
 
-TODO: explain the stopwatch plugin
+The ``StopwatchPlugin`` records the duration of HTTP requests with a
+``Symfony\Component\Stopwatch\Stopwatch`` instance::
+
+    use Http\Discovery\HttpClientDiscovery;
+    use Http\Client\Plugin\PluginClient;
+    use Http\Client\Plugin\StopwatchPlugin;
+    use Symfony\Component\Stopwatch\Stopwatch;
+
+    $stopwatch = new Stopwatch();
+
+    $stopwatchPlugin = new StopwatchPlugin($stopwatch);
+
+    $pluginClient = new PluginClient(
+        HttpClientDiscovery::find(),
+        [$stopwatchPlugin]
+    );
+
+    // ...
+
+    foreach ($stopwatch->getSections() as $section) {
+        foreach ($section->getEvents() as $name => $event) {
+            echo sprintf('Request %s took %s ms and used %s bytes of memory', $name, $event->getDuration(), $event->getMemory());
+        }
+    }
+
+.. warning::
+
+    The results of the stop watch will be unreliable when using an asynchronous client. Execution
+    time can be longer than it really was, depending on when the status was checked again, and
+    memory consumption will be mixed up with other code that was executed while waiting for the
+    response.