Cleanup: Adds documentation to Videorecorder.

src/VCR/Videorecorder.php

@@ -5,28 +5,49 @@
 use VCR\Util\Assertion;
 use VCR\Util\HttpClient;
 
+/**
+ * A videorecorder records requests on a cassette.
+ *
+ * If turned on, a videorecorder will intercept HTTP requests using
+ * hooks into libraries like cUrl, SOAP and streamWrappers.
+ * Requests and responses will be recorded on a inserted cassette.
+ * If a request is already recorded on a cassette the videorecorder
+ * will play back its response and not issue a HTTP request.
+ *
+ * If turned off, HTTP requests won't be intercepted and will
+ * hit their origininal servers.
+ *
+ * @author Adrian Philipp <mail@adrian-philipp.com>
+ */
 class Videorecorder
 {
     /**
-     * @var Configuration
+     * @var Configuration Config options like which library hooks to use.
      */
     protected $config;
 
     /**
-     * @var HttpClient
+     * @var HttpClient Client to use to issue HTTP requests.
      */
     protected $client;
 
     /**
-     * @var Cassette
+     * @var Cassette Cassette on which to store requests and responses.
      */
     protected $cassette;
 
     /**
-     * @var boolean
+     * @var boolean Flag if this videorecorder is turned on or not.
      */
     public $isOn = false;
 
+    /**
+     * Creates a videorecorder instance.
+     *
+     * @param Configuration $config  Config options like which library hooks to use.
+     * @param HttpClient    $client  Client which is used to issue HTTP requests.
+     * @param VCRFactory    $factory Factory which can create instances and resolve dependencies.
+     */
     public function __construct(Configuration $config, HttpClient $client, VCRFactory $factory)
     {
         $this->config = $config;
@@ -35,7 +56,10 @@ public function __construct(Configuration $config, HttpClient $client, VCRFactor
     }
 
     /**
-     * Initializes VCR and all it's dependencies.
+     * Turns on this videorecorder.
+     *
+     * This enables configured library hooks.
+     *
      * @return void
      */
     public function turnOn()
@@ -49,7 +73,10 @@ public function turnOn()
     }
 
     /**
-     * Shuts down VCR and all it's dependencies.
+     * Turns off this videorecorder.
+     *
+     * Library hooks will be disabled and cassettes ejected.
+     *
      * @return void
      */
     public function turnOff()
@@ -61,12 +88,27 @@ public function turnOff()
         }
     }
 
+    /**
+     * Eject the currently inserted cassette.
+     *
+     * Recording and playing back requets won't be possible after ejecting.
+     *
+     * @return void
+     */
     public function eject()
     {
         Assertion::true($this->isOn, 'Please turn on VCR before ejecting a cassette, use: VCR::turnOn().');
         $this->cassette = null;
     }
 
+    /**
+     * Inserts a cassette to record responses and requets on.
+     *
+     * @param  string $cassetteName Name of the cassette (used for the cassette filename).
+     *
+     * @return void
+     * @throws VCRExceptoin If videorecorder is turned off when inserting a cassette.
+     */
     public function insertCassette($cassetteName)
     {
         Assertion::true($this->isOn, 'Please turn on VCR before inserting a cassette, use: VCR::turnOn().');
@@ -82,11 +124,27 @@ public function insertCassette($cassetteName)
         $this->enableLibraryHooks();
     }
 
+    /**
+     * Returns the current Configuration for this videorecorder.
+     *
+     * @return Configuration Configuration for this videorecorder.
+     */
     public function configure()
     {
         return $this->config;
     }
 
+    /**
+     * Records, sends or plays back a intercepted request.
+     *
+     * If a request was already recorded on a cassette it's response is returned,
+     * otherwise the request is issued and it's response recorded (and returned).
+     *
+     * @param  Request $request Intercepted request.
+     *
+     * @return Response Response for the intercepted request.
+     * @throws \BadMethodCallException If there was no cassette inserted.
+     */
     public function handleRequest($request)
     {
         if ($this->cassette === null) {
@@ -107,6 +165,11 @@ public function handleRequest($request)
         return $this->cassette->playback($request);
     }
 
+    /**
+     * Disables all library hooks.
+     *
+     * @return void
+     */
     protected function disableLibraryHooks()
     {
         foreach ($this->config->getLibraryHooks() as $hookClass) {
@@ -115,6 +178,11 @@ protected function disableLibraryHooks()
         }
     }
 
+    /**
+     * Enables configured library hooks.
+     *
+     * @return void
+     */
     protected function enableLibraryHooks()
     {
         $self = $this;
@@ -129,7 +197,7 @@ function (Request $request) use ($self) {
     }
 
     /**
-     * Turns off VCR.
+     * Turns off this videorecorder when instance is destroyed.
      */
     public function __destruct()
     {