Merge pull request #26 from delatbabel/master

Add some more documentation

Author: greydnls

src/Omnipay/Common/AbstractGateway.php

@@ -17,6 +17,30 @@
  * throughout the Omnipay system.  It enforces implementation of
  * the GatewayInterface interface and defines various common attibutes
  * and methods that all gateways should have.
+ *
+ * Example:
+ *
+ * <code>
+ *   // Initialise the gateway
+ *   $gateway->initialize(...);
+ *
+ *   // Get the gateway parameters.
+ *   $parameters = $gateway->getParameters();
+ *
+ *   // Create a credit card object
+ *   $card = new CreditCard(...);
+ *
+ *   // Do an authorisation transaction on the gateway
+ *   if ($gateway->supportsAuthorize()) {
+ *       $gateway->authorize(...);
+ *   } else {
+ *       throw new \Exception('Gateway does not support authorize()');
+ *   }
+ * </code>
+ *
+ * For further code examples see the *omnipay-example* repository on github.
+ *
+ * @see GatewayInterface
  */
 abstract class AbstractGateway implements GatewayInterface
 {
@@ -214,7 +238,34 @@ public function supportsUpdateCard()
     }
 
     /**
-     * Create and initialize a request object using existing parameters from this gateway
+     * Create and initialize a request object
+     *
+     * This function is usually used to create objects of type
+     * Omnipay\Common\Message\AbstractRequest (or a non-abstract subclass of it)
+     * and initialise them with using existing parameters from this gateway.
+     *
+     * Example:
+     *
+     * <code>
+     *   class MyRequest extends \Omnipay\Common\Message\AbstractRequest {};
+     *
+     *   class MyGateway extends \Omnipay\Common\AbstractGateway {
+     *     function myRequest($parameters) {
+     *       $this->createRequest('MyRequest', $parameters);
+     *     }
+     *   }
+     *
+     *   // Create the gateway object
+     *   $gw = Omnipay::create('MyGateway');
+     *
+     *   // Create the request object
+     *   $myRequest = $gw->myRequest($someParameters);
+     * </code>
+     *
+     * @see \Omnipay\Common\Message\AbstractRequest
+     * @param string $class The request class name
+     * @param array $parameters
+     * @return \Omnipay\Common\Message\AbstractRequest
      */
     protected function createRequest($class, array $parameters)
     {
@@ -223,6 +274,11 @@ protected function createRequest($class, array $parameters)
         return $obj->initialize(array_replace($this->getParameters(), $parameters));
     }
 
+    /**
+     * Get the global default HTTP client.
+     *
+     * @return HttpClient
+     */
     protected function getDefaultHttpClient()
     {
         return new HttpClient(
@@ -233,6 +289,11 @@ protected function getDefaultHttpClient()
         );
     }
 
+    /**
+     * Get the global default HTTP request.
+     *
+     * @return HttpRequest
+     */
     protected function getDefaultHttpRequest()
     {
         return HttpRequest::createFromGlobals();