merged branch dlsniper/stopwatch (PR #5966)

This PR was merged into the master branch.

Commits
-------

bdf0334 Fixed the lap method. Added upgrade notes. Some CS fixes

Discussion
----------

Fixed the lap method. Added upgrade notes. Some CS fixes

Bug fix: yes
Feature addition: no
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: ~
Todo: ~
License of the code: MIT
Documentation PR: ~

This adds some type-hinting to the Stopwatch components.
I've also split the Section class to its own file, I know it's not a must as per coding standards used by Symfony but it complies with most of the other classes in the framework.
I've updated the UPGRADE-2.2.md file as well.

There's a bug fix which I'm not sure it if should have been done in this branch or not.

Let me know if I should make this PR against an older version of the framework.

Thanks.

UPGRADE-2.2.md

@@ -10,6 +10,8 @@
    `MongoDate` instead of `MongoTimestamp`, which also makes it possible to use
    TTL collections in MongoDB 2.2+ instead of relying on the `gc()` method.
 
+ * The Stopwatch functionality was moved from HttpKernel\Debug to its own component
+
 #### Deprecations
 
  * The `Request::splitHttpAcceptHeader()` is deprecated and will be removed in 2.3.

src/Symfony/Component/Stopwatch/Stopwatch.php

@@ -18,7 +18,14 @@ namespace Symfony\Component\Stopwatch;
  */
 class Stopwatch
 {
+    /**
+     * @var Section[]
+     */
     private $sections;
+
+    /**
+     * @var array
+     */
     private $activeSections;
 
     public function __construct()
@@ -54,6 +61,8 @@ class Stopwatch
      * @see getSectionEvents
      *
      * @param string $id The identifier of the section
+     *
+     * @throws \LogicException When there's no started section to be stopped
      */
     public function stopSection($id)
     {
@@ -117,11 +126,32 @@ class Stopwatch
     }
 }
 
+
+/**
+ * @internal This class is for internal usage only
+ *
+ * @author Fabien Potencier <fabien@symfony.com>
+ */
 class Section
 {
+    /**
+     * @var StopwatchEvent[]
+     */
     private $events = array();
+
+    /**
+     * @var null|float
+     */
     private $origin;
+
+    /**
+     * @var string
+     */
     private $id;
+
+    /**
+     * @var Section[]
+     */
     private $children = array();
 
     /**
@@ -236,7 +266,7 @@ class Section
      */
     public function lap($name)
     {
-        return $this->stop($name)->start();
+        return $this->stopEvent($name)->start();
     }
 
     /**
@@ -249,3 +279,4 @@ class Section
         return $this->events;
     }
 }
+

src/Symfony/Component/Stopwatch/StopwatchEvent.php

@@ -18,9 +18,24 @@ namespace Symfony\Component\Stopwatch;
  */
 class StopwatchEvent
 {
+    /**
+     * @var StopwatchPeriod[]
+     */
     private $periods;
+
+    /**
+     * @var float
+     */
     private $origin;
+
+    /**
+     * @var string
+     */
     private $category;
+
+    /**
+     * @var float[]
+     */
     private $started;
 
     /**
@@ -74,6 +89,8 @@ class StopwatchEvent
     /**
      * Stops the last started event period.
      *
+     * @throws \LogicException When start wasn't called before stopping
+     *
      * @return StopwatchEvent The event
      *
      * @throws \LogicException When stop() is called without a matching call to start()
@@ -184,7 +201,7 @@ class StopwatchEvent
     /**
      * Formats a time.
      *
-     * @param numerical $time A raw time
+     * @param integer|float $time A raw time
      *
      * @return float The formatted time
      *